Jump to: navigation, search

Unity (1.38)


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. 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.


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

Unity1.jpg ImportPackage.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;


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).


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;
         FuseAPI.RewardedVideoCompleted += RewardedVideoCompleted;

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;
         FuseAPI.RewardedVideoCompleted -= RewardedVideoCompleted;


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.


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


Next drag the FuseAPI prefab to the hierarchy.

Unity10.png Unity9.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


Before your App goes live you must configure your Zones, for more information see Here

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()
    private IEnumerator WaitAndCheckAd()
         yield return new WaitForSeconds(1);
    private void AdAvailabilityResponse(bool IsAdAvailable, FuseAPI.AdAvailabilityError error)
         if (IsAdAvailable)
              Debug.Log("AdAvailabilityResponse: "+ error.ToString());

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 true (meaning an ad is available) to trigger showing the ad, and starting the WaitAndCheckAd() coroutine in any other case.

The reasoning behind implementing the ad display algorithm in this way is that 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 SessionLoginError(FuseAPI.SessionError error)
        print ("SessionLoginError: " + error.ToString());
   private void AdWillClose()
         print ("AdWillClose");

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 Zone ID (string) will check if an ad is available for the zone with the corresponding ID. This will fire the AdAvailibilityResponse callback.



 FuseAPI.checkAdAvailable("Zone ID")

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.


Calling PreLoadAd is not mandatory, but it has a number of benefits, including the fact that it is less aggressive with timing out, allowing 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.


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


 public static event Action SessionStartReceived; 

Fired off when the session has been started

 public static event Action<SessionError> SessionLoginError; 

Fired off as a result of a session error. The parameter contains the session error


 public static event Action<bool, AdAvailabilityError> AdAvailabilityResponse;

Fired off as a result of calling check ad. First parameter is whether an ad was returned or not.

The second parameter is the error returned if no ad is available.


 public static event Action AdWillClose; 

Fired off when an ad has been clicked.

Tracking In App Purchases


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, AdRally™ 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)


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);


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.

AdRally can also track player levels using the following call.


Currency and Level data can be used to create cohorts.