Marmalade

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.

  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.

You can download our Marmalade wrapper on our Github Repository. This package contains everything you'll need to integrate FuseBoxx™ 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. For more info, see How to set up your 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 FuseBoxx™, the session per user KPI provides a means of gauging retention.

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

Push Notifications

Overview

For Android:

FuseBoxx™ offers the ability to schedule push notifications that leverage Google's Cloud Messaging service. To use this feature you must have registered for GCM through Google's API portal: Link Here. A good explanation of GCM can be found Here.

For iOS:

FuseBoxx™ offers the ability to schedule push notifications that leverage Apple's Push Notification Service. Click Here for an overview of the service. Before push notifications can be sent, Production and Development Certificates must be uploaded to FuseBoxx™ here:

https://www.fuseboxx.com/dashboard/pushnotifications/configure

Integration

To get Push Notifications working, you must replace notification_large.png and notification_small.png in FuseAPI/res/drawable with your own icons, The names must be the same.

notification_large is a 72x72 24-bit png

notifications_small is a 36x36 24-bit png

Once this is done, you can use the following function call to register for push notifications, enabling their functionality.

void FuseAPIRegisterForPushNotifications(const char* projectID);

projectID [const char*]: is the Project Number obtained after registering for GCM through Google's portal. The projectID value will be ignored on iOS.

If you are developing for Android:

In order to get push notifications working, you must navigate to FuseAPI/source/ExtraAppManifests.txt and replace com.fusepowered.marmaladesample with your application bundle ID. You must also navigate to FuseAPI/source/ExtraManifests.txt and replace com.fusepowered.marmaladesample with your application bundle ID for the two permissions.

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.

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. You can get retrieve the data from the server using the following call.

 const char* my_val = FuseAPIGetGameConfigurationValue("my_key");

Where:

"my_key": is the key for the app parameter you are retieving

Values are updated in the client each time a session is started from the Springboard or system tray. To find out when values are valid, you can use the following snippet to check that the values are ready to be inspected.

 if (my_val != NULL)
   {
       // always check against 'null' before using the value
   }

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.