Unity

From Fuseboxx Wiki
Jump to: navigation, search

NoteBubble.png

Important: Please test your integration on an iOS or Android device. Many API features, including ads, will ONLY work on a device.

Downloading the SDK

Before starting integration, you'll need to download the latest version of the Fuse SDK specific to your development environment.

  1. While AdRally is available to anyone, use of FuseBoxx™ requires an active partnership with Fuse Powered. Contact partners@fusepowered.com for all partnership inquiries.
  2. Sign in to FuseBoxx™ using your account credentials.

An open-source version of the Unity wrapper is available here. Any additions required to the wrapper can be made and compiled for your needs.

The Fuse Unity SDK will prompt you to update automatically when there is a new version available. You can change the auto update settings by selecting "FuseSDK > Preferences" from the menu bar.

Importing

Next you need to import the package into your Unity project.

Unity1.jpg ImportPackage.png

NoteBubble.png

You can also drag-and-drop the contents of the "Assets" folder from the wrapper directory to your Assets directory for your project

Set Up

First you should create the FuseSDK Prefab by selecting "FuseSDK > Regenerate Prefab" from the menu bar. The prefab will be generated as "Assets/FuseAPI/FuseSDK.prefab". The prefab will have the FuseAPI.cs script attached to it as seen below;

FuseSDKPrefab.png

The first step is to add your API Keys to the "Android Game ID" and/or "iOS Game ID" fields of the Fuse API component.

Then you need to create a script to call the API functions (for this example we'll use a C# script).

Unity3.jpg

You should register the callbacks on the Awake() function to ensure that they are bound before the session starts;

 void Awake()
 {
     FuseAPI.SessionStartReceived += SessionStarted;
     FuseAPI.AdAvailabilityResponse += AdAvailabilityResponse;
     FuseAPI.AdWillClose += AdWillClose;
     FuseAPI.SessionLoginError += SessionLoginError;
 }

We also need to complete the script by unregistering actions on onDestroy():

 void onDestroy()
 {
     FuseAPI.SessionStartReceived -= SessionStarted;
     FuseAPI.AdAvailabilityResponse -= AdAvailabilityResponse;
     FuseAPI.AdWillClose -= AdWillClose;
     FuseAPI.SessionLoginError -= SessionLoginError;
 }

NoteBubble.png

You can view a complete example script with Registering and Unregistering Callbacks Here.

Next, make sure that the C# script is attached as component within your scene.

Unity7.jpg

To test on a device, you'll first need to update the Bundle Identifier to match your profile (in Unity: Edit->Project Settings->Player)

Unity8.jpg

Next drag the FuseAPI prefab to the hierarchy.

Unity10.png Unity9.png

NoteBubble.png

For both iOS and Android platforms, the Fuse Unity wrapper will automatically collect push notifications tokens.

Starting a Session

In Unity, the Fuse session is started automatically.

Showing Ads

The fuse session is started automatically so you can start checking if an ad is available and display it if there is one;

 private void SessionStarted()
 {
     StartCoroutine(WaitAndCheckAd());
 }
 
 private IEnumerator WaitAndCheckAd()
 {
     yield return new WaitForSeconds(1);
     FuseAPI.CheckAdAvailable();
 }
 
 private void AdAvailabilityResponse(int IsAdAvailable, int HasError)
 {
     if (IsAdAvailable == 1)
     {
         FuseAPI.ShowAd();
     }
     else
     {
         StartCoroutine(WaitAndCheckAd());
     }
 }

In this example, we are implementing a function to check for ads periodically every second until one is found.

The "SessionStarted" callback is executed when the session has started, which executes the WaitAndCheckAd() function as a coroutine to wait for one second and check for an ad, to account for the ad waterfall retrieval period.

The "AdAvailabilityResponse" callback is executed after calling FuseAPI.CheckAdAvailable() and will tell you if an ad is available or if there's an error. This example shows using the returned value of "1" (meaning an ad is available) to trigger showing the ad, and starting the WaitAndCheckAd() coroutine in any other case.


The reason behind implementing the ad display algorithm in this way is because the ad waterfall may take some time to be retrieved from the server. Checking for ads immediately when the session has started will usually result in no ad being available to display.

You can pick up the closing of an ad with the AdWillClose callback or a session login error with the "SessionLoginError" callback and execute further code if you choose to.

 private void AdWillClose()
 {
     //AdWillClose
 }
 
 private void SessionLoginError(int obj)
 {
     //SessionLoginError
 }


Checking Ad Availability

When working in Unity, calling the checkAdAvailable method without passing a string will check if an ad is available for the default zone. Passing in a string will check if an ad is available for the zone named by the string. This will fire the AdAvailibilityResponse callback.

 FuseAPI.checkAdAvailable()

or

 FuseAPI.checkAdAvailable("Zone name")

Pre-Loading Ads

PreLoadAd works the same way. Passing no string pre loads for default zone, while passing a string pre loads for a specific zone. We recommend calling PreLoadAd for zone two or three seconds before calling show ad.

 FuseAPI.PreLoadAd()

Calling PreLoadAd is not mandatory, but it has a number of benefits, including the fact that it is less aggressive with timing out, allow for more opportunity to return higher paying ads.

Displaying Ads

Once you've checked the availability of a particular ad zone, you can show the ad using the method below.

 FuseAPI.ShowAd()

Passing no string shows default zone. Passing a string shows that zone, or pushes it to the dashboard.

Callbacks

 public static event Action<int, int> AdAvailabilityResponse;

Fired off as a result of calling check ad. First integer is whether an ad was returned or not.
0 = No ad available.
1 = Ad is available.

The second integer is the error code returned if no ad is available.
FUSE_AD_NO_ERROR = 0,
FUSE_AD_NOT_CONNECTED,
FUSE_AD_SESSION_FAILURE,


 public static event Action AdDisplayed; 

Fired off as a result of calling show ad

 public static event Action AdClicked; 

Fired off when an ad has been clicked.

Push Notifications

Overview

FuseBoxx™ offers the ability to schedule push notifications that leverage either Google's Cloud Messaging service or Apple Push Notification Service.

If you are developing for android you will need to register for GCM through Google's API Portal. A good explanation of GCM can be found here.

You will need to use your GCM key or APNS certificates in the (Toolboxx > Push Notifications > Configure) section of FuseBoxx™.

Integration

To integrate push notifications, all you have to do is make sure the Register For Push Notifications box is checked on the FuseAPI prefab when it is in the scene. If you are developing for android you will need to put your GCM Sender ID in the text field.

UnityPushNotificationsIos.png

The box is checked by default so you shouldn't need to do anything.


Delayed Push Token Registration

If you wish to delay push token registration (this means the permission popup will not appear until you register for push tokens), you can uncheck the Register For Push Notifications in the FuseAPI prefab.

When you wish to register for push notifications, call the following code in your Unity script:

 #if UNITY_IPHONE
 FuseAPI_iOS.FuseAPI_RegisterForPushNotifications();
 #else if UNITY_ANDROID
 FuseAPI.SetupPushNotifications( "GCM_SenderID" );
 #endif

Tracking In App Purchases

NoteBubble.png

If you are developing your app for Android, you must enable Purchase Validation through Google Play, Click Here for a guide

There are a few ways to track IAPs depending on your platform.

Prime 31 and Unibiller

If you are using Prime31 or Unibiller plugins for your in-app store, FuseBoxx™ can automatically track your user’s in-app purchases. Simply un-comment the first line in the respective C#script:

Prime 31

For iOS: #define USING_PRIME31_IOS (in Assets/FuseAPI/FuseAPI_Prime31StoreKit.cs)
For Android: #define USING_PRIME31_ANDROID (in Assets/FuseAPI/FuseAPI_Prime31_IAB.cs)

Unibiller

For iOS: #define USING_PRIME31_IOS (in Assets/FuseAPI/FuseAPI_Prime31StoreKit.cs)
For Android: #define USING_PRIME31_ANDROID (in Assets/FuseAPI/FuseAPI_Prime31_IAB.cs)

Both will automatically track the revenue for you and will begin the purchase validation process. If you wish to know the result, you must use the purchase verification method for your platform (detailed below).

Unity for Android

If you are using Android there are two separate calls, one with price and currency attached and one without, if you wish to record the price and currency of the IAP your call will look like:

FuseAPI.RegisterInAppPurchase(PurchaseState purchaseState, string notifyId, 
  string productId, string orderId, DateTime purchaseTime, string developerPayload, 
  double price, string currency);

and if you don’t wish to record price and currency:

FuseAPI.RegisterInAppPurchase(PurchaseState purchaseState, string notifyId,
  string productId, string orderId, DateTime purchaseTime, string developerPayload);

Unity for iOS

If you are building your app in Unity to target iOS, your call to track an IAP will look like this:

FuseAPI.RegisterInAppPurchase(productId, transactionId, transactionReceipt, transactionState);

Where:

productId is the identifier for the product being purchased

transactionId is the Apple identifier for the transaction

transactionReceipt is the encoded transaction receipt (needed to be passed as a byte array, see below)

transactionState is a Fuse Transaction State (simply one of PURCHASING, PURCHASED, FAILED, and RESTORED)


The transactionReceipt needs to be converted into a byte array before you can send it to our servers. You can use the following code snippet:

 byte[] reciept = Convert.FromBase64String(transaction.base64EncodedTransactionReceipt);
 FuseAPI.RegisterInAppPurchase(transaction.productIdentifier, transaction.transactionIdentifier, 
     reciept, FuseAPI.TransactionState.PURCHASED);

Purchase Verification Callbacks

All purchase verification callbacks within Unity are the same, regardless of platform:

   public static event Action<int, string, string> PurchaseVerification;

The first int parameter specifies what the result of the verification attempt was:
-1 = Not enough information to verifiy. This is often because the transaction identifier and/or receipt were missing when registerInAppPurchase was called.
0 = Verification failed. This implies that we were able to make contact with the verification service, but no match for the purchase was found.
1 = Successfully verified.

The second parameter is transaction ID.

The third parameter is the original transaction ID.

In most cases, the two transaction IDs will be identical. In the event of a purchase restoration, the transaction ID will be the ID of the restoration, while the original transaction ID will be the transaction ID of the original purchase.

Tracking Player Level and Currencies

To register an amount of currency for this player, use the following function call.

 FuseAPI.registerCurrency(5, 115);

Where the first parameter is the type of currency (1-4 being the 4 possible values) and the second parameter is the currency balance.

FuseBoxx™ can also track player levels using the following call.

 FuseAPI.registerLevel(5);

Currency and Level data can be used to create cohorts.

Using App Parameters

App Parameters are one of the most powerful tools FuseBoxx™ offers, it allows you to change the value of certain variables in your application without the need for iterative and time consuming updates. The App Parameters for your app are stored on FuseBoxx™ servers and can be updated at any time using FuseBoxx™. You can use the App Parameters you set to create Custom App Experiences, for more information on Custom Experiences Click Here

To start using App Parameters, go to the App Parameters Page (Toolboxx Tab > App Config > App Parameters). You can add a parameter by pressing the Add Parameter button at the button of the list. Once you have created a new parameter simply click the Key or the Value to select and input your data. Make sure all App Parameters you intend to use are Enabled. NewParameters.png

After the parameters have been set it's time to implement them into your code. There are two ways to retrieve the data from the FuseBoxx™ servers, the first is to pass in the specific Key into the following call:

 string gameVal;
 string key = "YourKey";
 gameVal = FuseAPI.GetGameConfigurationValue(key);

The second is to get all the parameters into a dictionary with the following call:

 Dictionary<String, String> my_vals = FuseAPI.GetGameConfig(); 

Values are updated in the client each time a session is started from the Springboard or system tray.

Now that you have the Parameters in code, you can assign them how you want.


NoteBubble.png

It is a good idea to both check the variables against nil to see if they are working as expected, as well as Initialize all the variables in your code in case the user has never connected to the internet.