Integration Guide - Android Unity APK games
- Laurentiu Popa
Before continuing with the rest of this document, make sure you are already familiar with https://nutakudoc.atlassian.net/wiki/spaces/ND/pages/3482386433, https://nutakudoc.atlassian.net/wiki/spaces/ND/pages/3482517521 and https://nutakudoc.atlassian.net/wiki/spaces/ND/pages/3482124347 pages.
This documentation is NOT written to be self-sufficient. For a complete understanding of integration you are expected to check out the included sample TestUIController.cs code from the SDK unitypackage file.
WebGL notice
The code and flows from Nutaku Android Unity SDK are only applicable for Android, they are not compatible with Nutaku PC Browser integration. Because of this, all SDK files are inside a “#if UNITY_ANDROID“ compiler directive. If you are using the same Unity project for both Android and WebGL development, you will have to wrap all your calls to Nutaku SDK inside the same compiler directive to avoid compiler errors in WebGL mode.
Unity Version
Minimum supported: 2021.2
At the time of writing this documentation, Unity 6000 is confirmed supported.
Setup and usage of the Sample App
If you haven’t already integrated a game on GI2 system on Nutaku, we strongly recommend that you start by first preparing a project for this sample app view and to try it out.
Download the latest Unity variant of the Android SDK from the Documents section of the CMS. Note that Game Integration 2.0 requires Nutaku SDK 4.0.0 or above!
Optional: Create a new project (nothing fancy is required for Unity templates, even 2D templates are fine. All that is needed is UnityEngine and support for Android builds. Everything else Unity is trying to promote can be disabled if you want)
This step is marked as optional because you can instead choose to use your real game project and you can swap between your game scene and the included sdk Sample Scene manually. Up to you if you prefer 2 separated projects or one that you toggle scenes. The verbiage in the rest of these steps assumes a new project was created.Import the sdk unitypackage in your project (usually in the top menu → Assets → Import Package → Custom Package).
If you chose to skip step 2, then for the AndroidManifest.xml file conflict please read the step about the Manifest from the next section.If you are using Unity 2021 or 2022: in the AndroidManifest.xml comment/delete the activity element named “
com.unity3d.player.UnityPlayerGameActivity“ and uncomment the activity element named “com.unity3d.player.UnityPlayerActivity“Set the target platform to Android (depends on Unity version, but generally under File → Build Profiles → Select Android from the list → Switch Platform)
Add/drag the SDK’s Sample scene into the scene list. If this is a project just for the sample app, you can delete the default Unity sample from that section (right click → remove)
Open the Build Profiles and in the Scene List ensure you add the Nutaku Sample scene and that you enable it (you can remove the one that Unity had before). The actual click sequence for this step depends on Unity version.
Open the Player Settings (button location depends on Unity version. For Unity 6 can be from File → Build Profiles → Player Settings (top-right). Other unity versions have the button at the bottom)
set the package name to something that doesn’t use underscores or uppercase characters. For some unity versions you will also have to enable “override default package name”. Also remember the value you set, it will be used in the next step.
enable Custom Main Manifest (usually found in the Publishing Settings sub-section of the Player Settings)
Open Assets\Plugins\Nutaku\Scripts\NutakuSdkConfig.cs
set TitleId to the value you registered in the CMS
set AndroidPackageName to the value you set in the Player Settings in the previous step
Done! Pressing the play button at the top should allow functional interaction with the sample app in the Unity Editor. You can also build it as an APK and run it on an Android OS/simulator.
All the code for the buttons and how they interact with the sdk are found in TestUIController.csIf you are not already familiar with Nutaku Game Integration 2.0 server-side APIs for Payments and for Game Handshake, we recommend you start implementing them while using this Sample App as a testing and troubleshooting tool for your server implementation.
Setup for your actual game project
If you haven’t first built the Sample App and played with it, we strongly recommend you do that first, otherwise the integration in your real game will be cumbersome and potentially confusing.
Download the latest Unity variant of the Android SDK from the Documents section of the CMS. Note that Game Integration 2.0 requires Nutaku SDK 4.0.0 or above!
Import the sdk unitypackage in your project (usually in the top menu → Assets → Import Package → Custom Package).
If your project already has an AndroidManifest.xml file you should choose one of the following approaches, depending on which one you find easier/faster:Back up your existing manifest and import the one from the nutaku sdk unitypackage
Keep your existing manifest file (deselect the manifest from the sdk package import) and then do the following 2 manual snippet insertions in the manifest:
inside the <manifest> element. This is to allow the Nutaku Android Store app to detect the presence of your game on the device.
<queries> <package android:name="com.project.nutaku"/> </queries>inside the <activity> element, right after your existing <intent-filter>
<intent-filter> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="${applicationId}" android:host="callback" android:path="/param" /> </intent-filter>You can leave “${applicationId}“ as is. The compiler should automatically replace it with your package identifier.
If, for any reason your existing manifest doesn’t already have an activity element, you can just copy the entire appropriate element from the manifest from the nutaku sdk.
Open the Player Settings (button location depends on Unity version. For Unity 6 can be from File → Build Profiles → Player Settings (top-right). Other unity versions have the button at the bottom)
set the package name to something that doesn’t use underscores or uppercase characters. For some unity versions you will also have to enable “override default package name”. Also remember the value you set, it will be used in the next step.
enable Custom Main Manifest if not already enabled (usually found in the Publishing Settings sub-section of the Player Settings)
if building for production environment: also take note of the Bundle Version Code. Very important that every time you change this value in the future to also update it inside NutakuSdkConfig file.
Open Assets\Plugins\Nutaku\Scripts\NutakuSdkConfig.cs
[one time] set TitleId to the value you registered in the CMS
[one time] set AndroidPackageName to the value you set in the Player Settings in the previous step
set Environment to the appropriave value: SANDBOX or PRODUCTION
[one time] set loginResultToGameCallbackDelegate and paymentBrowserResultToGameCallbackDelegate to your game’s implementations. This is where familiarity with the Sample app code is very important. You can delay this sub-step for later so you don’t get compile errors as you implement your respective methods.
Add trigger to initialize the sdk (
NutakuSdk.Initialize(this)) from a MonoBehavior-inheriting class, as early as possible in your startup flow, such as in the Awake() of your primary startup scene.Write your implementations of the triggering methods and the callback methods for Login (the one from config), Game Handshake, Create Payment, Put Payment, the payment callback from config and checking for APK updates.
Take heavy inspiration from the comments/Logmessages provided in TestUIController.
Remember to update the 2 callback delegates from the NutakuSdkConfig file after you implement them.Done, you should be able to test your app in UnityEditor or build it as Android APK.
General User startup/login flow in a Nutaku Android game
The below flow covers happy user paths (aka does not cover error scenarios).
User (cold) starts the apk on the phone.
The game calls NutakuSdk.Initialize() which checks if the user was already logged in by performing the autologin function.
If autologin successful, skip to step 7.SDK opens the login page in the device’s browser (it will also call your login delegate with wasSuccess=false so your app shows the respective waiting overlay/modal with the button).
If the user isn’t already logged in on the browser, they will be asked for credentials.
If the user chooses to close the browser tab instead of providing credentials, when they open your app again, they will see the overlay/modal from step 3 still on the screen. The only thing they are allowed to do is to press that button which will take them back to step 4.
Browser page sends an intent (deeplink) to your apk with auth and profile details.
The SDK processes the details and triggers lor login callback, this time with wasSuccess=true - which contains your implementation for a successful login. You can read the user id NutakuCurrentUser class.
[this step can be moved after the next step if you want] The game code should now make use of NutakuApi.CheckForNewerPublishedApk() feature to ensure the user is running on the latest published APK, and informing him using your own visual design for the message/prompt.
Your game now needs to use the NutakuApi.GameHandshake() feature to ensure the user id from NutakuCurrentUser.GetUserId() is not manipulated to impersonate anyone, and to ensure future game client to game server communications are properly authenticated (for example by sending NutakuCurrentUser.GetUserId() value along with the session/token from GameHandshake back to your server and your server compares this user id with the user id it received from the S2S handshake call from Nutaku)
Once all of the above is done, the user now gets to your main menu, or equivalent screen - And you can read all the user details using the getters from the NutakuCurrentUser class.
Payment Flow
This is just an overall step list. For more details we recommend checking the payment creation implementation from the Sample TestUIController (especially the messages inside the logs) and the https://nutakudoc.atlassian.net/wiki/spaces/ND/pages/3482124347
The flow from this page is also only with happy user paths (doesn’t include error scenarios)
User clicks on an item in your in-game store.
You feed your item details into NutakuPayment.PaymentCreationInfo() to get a NutakuPayment object.
Your code calls NutakuApi.CreatePayment() using the above object and a payment creation callback delegate.
Nutaku server calls your GPHS with POST.
Your GPHS validates the data, stores the details in the DB/persistent storage and returns success to Nutaku.
SDK returns the NutakuPayment object to the game code via your payment creation callback.
You parse the rawResult using NutakuApi.Parse_CreatePayment()
If parsedResult.next == “put”: you show an in-game prompt with the item image, name and Nutaku gold price, along with confirmation and cancel buttons.
ELSE: browser is needed, skip to step 13.If User presses the confirmation, the game calls NutakuApi.PutPayment() with the payment id and a callback for put payment.
Nutaku server charges the user for the item price and calls your GPHS with PUT.
Your GPHS awards the item to the user and sends the success back to Nutaku server.
The SDK will inform the game of the result via your callback for put payment.
Yor callback evaluates the put payment result:
HTTP 200 - payment was completed, inform the user and refresh his inventory/state. FLOW END.
HTTP 424 - FLOW END - Error caused by your Game Payment Handler Server not responding positively to the S2S PUT Request. See https://nutakudoc.atlassian.net/wiki/spaces/ND/pages/3482124347.
anything else - payment could not be completed via PUT, therefore your game can start the browser approach, step 13.
The game calls NutakuSdk.OpenTransactionUrlInBrowser() with the PaymentId of NutakuPayment object from step 7. The browser is opened.
Optionally you can show a modal/prompt at the same time that the user can cancel. But be aware that the user cancelling the purchase does not mean you can discard it. The user has an hour to still complete the payment in the browser, out of sequence!User completes or cancels the transaction in the browser. The SDK will notify the game about this via the payment callback delegate you specified in the NutakuSdkConfig. You will receive the paymentId and the outcome status for it.
Remember, the statusFromBrowser is vulnerable to manipulation. It should only be used as a hint/trigger to check with your game server inventory state, rather than a guaranteed legit situation.If status==”cancel“: FLOW END, no need to inform the user, he pressed cancel in the browser. Dismiss the modal/overlay if you had one showing.
if status==”purchase”: FLOW END BUT CHECK WITH YOUR SERVER FOR LEGITIMACY.
If status==”errorFromGPHS”: FLOW END, Error caused by your Game Payment Handler Server not responding positively to the S2S PUT Request. See https://nutakudoc.atlassian.net/wiki/spaces/ND/pages/3482124347
If status has any other value: FLOW END, no need to inform the user, he saw the error in the browser already. Dismiss the modal/overlay if you had one showing.