Jump to: navigation, search

Marmalade (1.38)

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. You can download our Marmalade wrapper on our Github Repository. This package contains everything you'll need to integrate AdRally™ in to your Marmalade based applications. For a detailed explanation of all the FuseAPI function calls, see FuseAPI/docs/FuseAPI.txt within the downloaded directory (or click here for a direct link).

Set Up

Once you've downloaded the FuseAPI Marmalade wrapper, you must include the FuseAPI in your marmalade project.

  1. Copy the FuseAPI directory into your extensions folder.
  2. Subproject the FuseAPI Extension in your Marmalade Project's MKB File:
subprojects
{
     FuseAPI
}

NoteBubble.png

For an example of what your .mkb file should look like Click Here

To use the FuseAPI extension in your project, first include the FuseAPI header:

 #include "FuseAPI.h"

Next call the StartSession method.

Register Callbacks

Before you start a session you should register Fuse callbacks. Doing so will allow the FuseAPI to send messages to your game.

For detailed explanations of all callbacks, see FuseAPI/docs/Callbacks.txt. Or Click Here for a direct link.

Registering callbacks should look like this:

FuseAPIRegister(FUSEAPI_SESSION_STARTED, &GotSessionReceived, NULL);
FuseAPIRegister(FUSEAPI_SESSION_LOGIN_ERROR, &SessionLoginError, NULL);

Your callback handling functions, as defined in your code, should look like this:

int32 GotSessionReceived(void* systemData, void* userData)
{
      //Handle callback here
      return 1;
}

All of these are in the format of FuseAPIRegister(Fuse Function, &CallbackHandlerName, Variable)

&CallbackHandlerName refers to whatever function will be called once a callback has been received. In the above example, after starting your session, a function named GotSessionReceived will be called.

Unregistering Callbacks

When the game is terminated, you must unregister that callback function you have created, which should look like this:

FuseAPIUnRegister(FUSEAPI_SESSION_STARTED, &GotSessionReceived);
FuseAPIUnRegister(FUSEAPI_SESSION_LOGIN_ERROR, &SessionLoginError);

The FuseAPIUnRegister function should have the callback id and the reference to the callback handling function as parameters.

NoteBubble.png

For an example of what your .cpp file should look like with registering and unregistering Callbacks Click Here

Starting a Session

The most important function call is to register the start of an app session. By passing it the assigned API key, this function will authenticate your application with the Fuse servers. To set up Marmalade to work with both iOS and Android, use the following code.

if (s3eDeviceGetInt(S3E_DEVICE_OS) == S3E_OS_ID_IPHONE)
{
    FuseAPIStartSession("Your iOS API Key");
}
else
{
    FuseAPIStartSession("Your Android API Key");
}

Note that either of the FuseAPIStartSession calls will work by themselves. If you are only developing an app for one platform, the if statement is unnecessary.

Session information is the key metric used for tracking when a user is in the app, and is a component for a certain KPI's (Key Performance Indicators). For example, in the main page of AdRally™, the session per user KPI provides a means of gauging retention.

Your API key is generated when you add your App to AdRally™. It can be found in the configuration tab in a specific game, or in the "Integrate API" section of AdRally™ (Admin Tab > Integrate SDK on AdRally™.com). The API key is s 36-digit unique ID.

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.

Marmalade on Android

If you are developing for android the call is:

FuseAPIRegisterInAppPurchase(PurchaseState purchaseState, const char* purchaseToken,
   const char* productId, const char* orderId, long purchaseTime, 
   const char* developerPayload, const double* price, const char* currency);

And this call uses the following parameters:

purchaseState [PurchaseState]: An object set to the purchase details for easy parsing by the Fuse system (PURCHASED=0, CANCELLED=1, REFUNDED=2)

purchaseToken [const char*]: The token from the purchase transaction

productId [const char*]: The product identifier

orderId [const char*]: The order identifier

purchaseTime [long]: Timestamp of the purchase

developerPayload [const char*]: Developer payload from the purchase

price [const double*]: Purchase price

currency [const char*]: Currency code

Marmalade on iOS

If you are developing for iOS the call is:

void FuseAPIRegisterInAppPurchaseiOS(PurchaseState purchaseState, const  char* receiptData,
double* price, const char* currency, const char* productID);

And this function uses the following parameters:

purchaseState [PurchaseState]: An object set to the purchase details for easy parsing by the Fuse system (PURCHASING=0, PURCHASED=1, FAILED=2, RESTORED=3)

receiptData [const char*]: The receipt from the purchase transaction (this should be encoded in base 64)

price [const double*]: Purchase price

currency [const char*]: Currency code

productId [const char*]: The product identifier

Tracking Player Level and Currencies

To register a player's level, use the following syntax where appropriate (most likely where a level up occurs):

 void FuseAPIRegisterLevel(int level);

Where level is the player's current level.

The Fuse Event Tracking system can also track 4 different currency balances, to register one of these balances use the following syntax:

 void FuseAPIRegisterCurrency(int type, int balance);

'type' refers to a number between 1 and 4 referring to the currency balance being tracked.