Android Unity Integration

The Skillz Android Unity wrapper is available for both JavaScript (.js) and C# (.cs) projects. Download the Skillz Unity wrappers in the Downloads Tab of your Developer Portal.


For a step-by-step (commit-by-commit) integration code sample, check out our sample game, 3d-cave-runner. 3D cave Runner is also available for download. Go to skillz.com on your Android phone.

 

Step 1: Import the Appropriate Skillz Wrapper in your Unity Project

 

Import the Skillz Wrappers inside Assets/Scripts of your Unity Project. Make sure to import the appropriate wrappers for your game (C# or JS).

You can also check out this commit from our sample game 3D Cave Runner to see how the Skillz wrapper were imported into the Unity Project.

Step 2: Handling The Skillz Activity

 

Unity functions are analogous to the Skillz native Android function calls outlined in the Native Android Skillz documentation.

 Skillz.Launch()
 Skillz.IsMatchInProgress() => boolean
 Skillz.GetMatchRules() => Hashtable
 Skillz.UpdatePlayersCurrentScore(score)
 Skillz.ReportScore(score)
 Skillz.AbortMatch()
 Skillz.Random => Random class to be used for fair RNG instead of Unity's Random.

Skillz.Random contains comparable methods to Unity’s Random:

 Value()
 Range(min,max)
 Rotation()
 InsideUnitSphere()
 InsideUnitCircle()
 OnUnitSphere()

These directly replace UnityEngine.Random properties and methods. Note that the Skillz versions are all method calls; for example, you would replace UnityEngine.Random.onUnitSphere with Skillz.Random.OnUnitSphere().

You can also check out this commit from our sample game 3D Cave Runner to see how to call the Skillz methods in your project. 

Step 3: Create a new empty GameObject called SkillzDelegate

 

In the scene that Skillz is launched from, attach the SkillzDelegate.cs/SkillzDelegate.js script to it

Important: The GameObject must be named SkillzDelegate to work properly with Skillz

 

Step 4: Implement the methods within the SkillzDelegate script

 

SkillzMatchStarted() is called when a user enters a match from Skillz and control is handed back to your game. This implementation should start a Skillz match. This function call is required since this is the callback that actually starts a Skillz Match.

SkillzExited() is called when a user exits Skillz (via Menu -> Exit) and control is handed back to your game. This implementation should show your game’s main menu or splash screen. This function call is optional. You won’t need this function call if your game is a skillz only game and there is no main menu to go to.

 

Step 5: Export Unity project as Android project

 

On the Header bar of Unity, go to File > Build Settings:

Make sure to check “Google Android Project” then click “Export”

 

Step 6: Import into Android Studio

 

On the Header bar of Android Studio, go to File > New > Import Project (Select exported directory).

FYI: Importing into Android Studio should add gradle support.

 

Step 7: Be sure to set the minimum and target Android SDK versions

 

In your build.gradle file, you will need to ensure the Android SDK version compatibility. Skillz requires a minSdkVersion of 19 or higher, and works best with a compiledSdkVersion of 25 and targetSdkVersion of 22. If you want to learn more about what's the difference between compiledSdkVersion and targetSdkVersion, you can check out the official Android developer documentation.

build.gradle:

android {
    compileSdkVersion 25
    buildToolsVersion "25.0.0"

    defaultConfig {
        applicationId "com.skillzgames.caverun"
        minSdkVersion 19
        targetSdkVersion 22
    }

    (...)
}

A targetSdkVersion of 23 (6.0) or higher will cause permission problems. Users may be repeatedly asked to grant location permissions, even if they have done so in the past. This is due to the new on-demand permissions paradigm introduced with this version of Android. Setting your targetSdkVersion values to 22 will avoid these issues.

Ensure minSdkVersion is set to 19 or higher and that the targetSdkVersion is set to 22 or higher within the android { defaultConfig { } } block of your build.gradle.

Additionally, ensure that the compiledSdkVersion within the android block is set to 25 or lower.

Finally, set the uses-sdk line within the <manifest> block of your AndroidManifest.xml file to match these settings:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.skillz.caverun" />
<uses-sdk android:minSdkVersion="19" android:targetSdkVersion="22" />

Step 8: Adding the Skillz Library in Android Studio

 

Note: This step is steps 1 and 2 of this article: https://cdn.skillz.com/doc/developer/android_native/integrate_skillz_sdk/adding_the_skillz_library/

Inside your build.gradle file, add the Skillz Maven Repository like so:

repositories { 
    maven {
        url 'http://nexus.skillz.com/content/groups/public/'
    }
}

Next, you will need to add the Skillz library as a dependency:

dependencies { 
    ...
    compile 'com.skillz.sdk:skillz-sdk-android:3.2.1'
    ...
}

Note: that version specified in the example above, '3.2.1', is a hardcoded version number, you will have to periodically change the version of the Skillz SDK to the latest version - just as you would any other outdated dependency in your project.

Step 9: Configure AndroidManifest.xml for Skillz

 

A few modifications need to be made to the AndroidManifest.xml file that was exported from Unity for your game.

Set Skillz Metadata values

  • skillz_game_activity should be left blank (“”)
  • skillz_is_unity should be set to true

This corresponds to the following lines:

<meta-data android:name="skillz_game_activity" android:value="" />
<meta-data android:name="skillz_is_unity" android:value="true" />

Full example set of Skillz meta-data:

<application>
    <!-- Make sure skillz_is_unity is a direct child of <application> like the rest of the Skillz <meta-data> tags! -->
    <meta-data android:name="skillz_game_id" android:value="2112" />
    <meta-data android:name="skillz_production" android:value="false" />
    <meta-data android:name="skillz_orientation" android:value="portrait" />
    <meta-data android:name="skillz_allow_exit" android:value="true" />
    <meta-data android:name="skillz_game_activity" android:value="" />
    <meta-data android:name="skillz_is_unity" android:value="true" />
</application>

Now, edit each meta-data line to contain the correct information for your game.

<meta-data android:name="skillz_game_id" android:value="" />

Set the value to your Skillz Game ID from the Skillz Developer Portal. You can obtain your Game ID by going to your developer portal.

<meta-data android:name="skillz_production" android:value="false" />

Set this value to “false” for testing in the sandbox environment. When you are ready to move to production and before uploading a binary in your developer portal, set this value to “true”.

<meta-data android:name="skillz_orientation" android:value="portrait" />

Set this value to “portrait” or “landscape” depending on your game’s orientation. Games that rotate between landscape and portrait are not supported at this time.

<meta-data android:name="skillz_game_activity" android:value="" />

This value should be left black since your game is a Unity game.

<meta-data android:name="skillz_allow_exit" android:value="true" />

Set the value to “true” to allow users to exit the Skillz interface back to the main menu of your game. Set the value to “false” if your game is Skillz-only and there is no main menu of your game.

<meta-data android:name="skillz_is_unity" android:value="true" />

Set this value to "true" since your game is a Unity game.

 

Add or Modify the following Android Values

The Activity attributes of launchMode, clearTaskOnLaunch, and alwaysRetainTaskState should be set to use the following values. This allows the user to return to the current state of the game after backgrounding it.

<activity
android:launchMode="singleTop"
android:clearTaskOnLaunch="false"
android:alwaysRetainTaskState="true">
(...) </activity>

Note: You may need to add this meta-data tag 

<meta-data android:name="android.max_aspect" android:value="2.1" /> 

to support the larger aspect ratio of the new Android flagship phones.

 

Step 10: Compile and test your game

 

Unity games plus the Skillz SDK usually results to a higher Dex count than the accepted limit. As a result, you will need to enable ProGuard and/or MultiDex. When you are ready to go live, this document will teach you how to switch from Sandbox to Production.

Tip: if you re-compile and re-export your Unity game, you don’t have to re-import the entire project into Android Studio. Instead, you can copy the assets directory from the exported project into app/src/main/ (replacing the existing assetsdirectory) and simply perform a clean build from there.