Jump to: navigation, search

Marmalade

Marmalade Integration

NoteBubble.png

Important: Please test your integration on a device. Fuse 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. You can download the Marmalade SDK Here. You can refer to this page for the FuseSDK Code Reference.

Importing

Once you have downloaded the SDK you need to copy the FuseSDK directory into your extensions folder. When this is complete you can import FuseSDK classes. To do that, Subproject the FuseSDK Extension in your Marmalade Project's MKB file;

  subprojects
  {
      FuseSDK
  }

Set up

Manifest

NoteBubble.png

The minimum supported target is API level 11

You need to make the following change in your manifests;

  • Edit FuseSDK/source/android/ExtraManifests.txt, replace com.fusepowered.marmaladesample with your application bundle ID

Push Notifications Icons

Replace notification_large.png and notification_small.png in FuseSDK/res/drawable with your own icons. Please make sure the names of the new icons are the same.

  • notification_large.png is a 72x72 24-bit png
  • notification_small.png is a 36x36 24-bit png

Using the SDK

To use the FuseSDK extension in your project, first include the FuseSDK header

  #include "FuseSDK.h"

Registering Callbacks

Many FuseSDK callbacks send information as structs through the systemData parameter. You need to register the callbacks as soon as the app has been initialized using FuseSDKRegister method;

      // session start
      FuseSDKRegister(FUSESDK_SESSION_STARTED, &GotSessionReceived, NULL);
      FuseSDKRegister(FUSESDK_SESSION_LOGIN_ERROR, &SessionLoginError, NULL);
  
      // account login
      FuseSDKRegister(FUSESDK_ACCOUNT_LOGIN_COMPLETE, &LoginComplete, NULL);
  
      // ad availability
      FuseSDKRegister(FUSESDK_AD_AVAILABILITY_RESPONSE, &AdAvailableResponse, NULL);
      FuseSDKRegister(FUSESDK_AD_WILL_CLOSE, &AdWasClosed, NULL);
      FuseSDKRegister(FUSESDK_REWARDED_AD_COMPLETED, &RewardedAdCompleted, NULL);
      FuseSDKRegister(FUSESDK_IAPOFFER_ACCEPTED, &IAPOfferAccepted, NULL);
      FuseSDKRegister(FUSESDK_VIRTUALGOODSOFFER_ACCEPTED, &VGOfferAccepted, NULL);
  
      // iap tracking
      FuseSDKRegister(FUSESDK_PURCHASE_VERIFIED, &PurchaseVerified, NULL);

You also need to unregister the callbacks at the end of your app's life cycle using FuseSDKUnRegister method;

      FuseSDKUnRegister(FUSESDK_SESSION_STARTED, &GotSessionReceived);
      FuseSDKUnRegister(FUSESDK_SESSION_LOGIN_ERROR, &SessionLoginError);
      FuseSDKUnRegister(FUSESDK_AD_AVAILABILITY_RESPONSE, &AdAvailableResponse);
      FuseSDKUnRegister(FUSESDK_AD_WILL_CLOSE, &AdWasClosed);
      FuseSDKUnRegister(FUSESDK_ACCOUNT_LOGIN_COMPLETE, &LoginComplete);
      FuseSDKUnRegister(FUSESDK_REWARDED_AD_COMPLETED, &RewardedAdCompleted);
      FuseSDKUnRegister(FUSESDK_IAPOFFER_ACCEPTED, &IAPOfferAccepted);
      FuseSDKUnRegister(FUSESDK_VIRTUALGOODSOFFER_ACCEPTED, &VGOfferAccepted);
      FuseSDKUnRegister(FUSESDK_PURCHASE_VERIFIED, &PurchaseVerified, NULL);

Information about callbacks and the structures they pass can be found in FuseSDK/docs/Callbacks.txt

For implementation of the callback methods, please see below.

Starting a Session

The most important function call is to register the start of an app session. The Fuse servers identify the app using the app ID that was generated for your app in the dashboard. To do this, you should call FuseSDKStartSession as soon as the app is initialized, right after you register the callbacks:

  FuseSDKStartSession("YOUR APP ID", NULL); 

Session information is the key metric used for tracking when a user is in the app, and is a component for certain KPI's (Key Performance Indicators).

The Callback:

The FuseSDKStartSession method will receive either the FUSESDK_SESSION_STARTED callback or the FUSESDK_SESSION_LOGIN_ERROR callback, based on the success of the operation;

  int32 GotSessionReceived(void* systemData, void* userData)
  {
      //Session started successfully
      return 1;
  }

  int32 SessionLoginError(void* systemData, void* userData)
  {
      //Session Failed to start
      struct paramList
      {
          int error;
      };
      const paramList* params = (paramList*)systemData;
  
      return 1;
}

The error codes contained within the systemData parameter are as follows;

  • 0: No error has occurred
  • 1: The user is not connected to the internet
  • 2: There was an error in establishing a connection with the server.
  • 3: Data was received, but there was a problem parsing the xml.
  • 4: The server has indicated the data it received was not valid.
  • 5: The session has recieved an error and the operation did not complete due to this error.
  • 6: The request was not valid, and no action will be performed.
  • 7: Unknown error.

Showing Ads

NoteBubble.png

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

Caching Ads

You can use the method FuseSDKPreloadAdForZoneID to fetch an ad, offer, or rewarded video from the given zone and prepare it to be shown;

  FuseSDKPreloadAdForZoneID("ZONE ID");

This will receive the FUSESDK_AD_AVAILABILITY_RESPONSE callback;

  int32 AdAvailableResponse(void* systemData, void* userData)
  {
      struct paramList
      {
          int available;
          int error;
      };
      const paramList* params = (paramList*)systemData;
    
      if( params->available > 0 )
      {
          //Displaying Ad
      }
      else if( params->error > 0 )
      {
          //Error fetching ad
      }
      else
      {
          //No Ads to display
          return 1;
      }
    
      return 1;
  }

This method is optional and is used to help ensure that an ad is shown in a timely manner. If the zone is not ready to display an ad, this will start loading an appropriate ad but will not show it until FuseSDKShowAdForZoneID is called. If an ad is ready to be displayed, it does nothing. This callback is always received after calling this method.

Downloading an ad could take several seconds, depending on the size of the ad and connection speed. For best results, you should allow ample time for the ad to finish loading before attempting to show it. For example, when a game has a level completed screen and wants to show an ad when the user chooses to start the next level, you should call FuseSDKPreloadAdForZoneID as soon as the level is completed and FuseSDKShowAdForZoneID when the next level button is pressed.

The error codes and their meanings are as follows;

  • 0: No error has occurred
  • 1: The user is not connected to the internet
  • 2: There was an error in establishing a connection with the server.
  • 3: Data was received, but there was a problem parsing the xml.
  • 4: The server has indicated the data it received was not valid.
  • 5: The session has recieved an error and the operation did not complete due to this error.
  • 6: The request was not valid, and no action will be performed.
  • 7: Unknown error.

You can only cache one zone at a time; if you call this method for more than one zone, the latter calls will overwrite the formerly cached zone.

Display Ads

Use the FuseSDKShowAdForZoneID method for displaying ads;

  FuseSDKShowAdForZoneID("ZONE ID", NULL);

This method attempts to display an ad if one is available. If no ad is immediately ready to display, this method waits up to 3 seconds for an ad to load and displays immediately if loading finishes.

This method will always receive the FUSESDK_AD_WILL_CLOSE callback; either when the ad is closed, or when no ads are loaded before timing out.

  int32 AdWasClosed(void* systemData, void* userData)
  {
      // Ad Was Closed
      return 1;
  }

Rewarded Ads

You can enable Pre-Roll and Post-Roll messages when you want to display a rewarded ad.

  // show ad from Rewarded Video ad zone with a preroll and a postroll message
  cfuhash_table_t* options = cfuhash_new_with_initial_size(2);    
  
  //Note: both the key and the value need to be strings
  cfuhash_put(options, kFuseSDKRewardedAdOptionKey_ShowPreRoll, "1"); //Enable Pre-Roll Message
  cfuhash_put(options, kFuseSDKRewardedAdOptionKey_ShowPostRoll, "1"); //Enable Post-Roll Message
  
  FuseSDKShowAdForZoneID("REWARDED VIDEO ZONE ID", options);

Similarly, you can customize the button text on the alerts.

  // show ad from Rewarded Video ad zone with a preroll and a postroll message
  cfuhash_table_t* options = cfuhash_new_with_initial_size(5);    
  
  //Note: both the key and the value need to be strings
  cfuhash_put(options, kFuseSDKRewardedAdOptionKey_ShowPreRoll, "1"); //Enable Pre-Roll Message
  cfuhash_put(options, kFuseSDKRewardedAdOptionKey_ShowPostRoll, "1"); //Enable Post-Roll Message
  cfuhash_put(options, kFuseSDKRewardedOptionKey_PreRollYesButtonText, "Yes"); //Set text for the "Yes" button here
  cfuhash_put(options, kFuseSDKRewardedOptionKey_PreRollNoButtonText, "No"); //Set text for the "No" button here
  cfuhash_put(options, kFuseSDKRewardedOptionKey_PostRollContinueButtonText, "Continue"); //Set text for the "Continue" button here
  
  FuseSDKShowAdForZoneID("REWARDED VIDEO ZONE ID", options);

If the user should receive a reward, this method will receive the FUSESDK_REWARDED_AD_COMPLETED callback.

  int32 RewardedAdCompleted(void* systemData, void* userData)
  {
      struct paramList
      {
          const char* preMessage;
          const char* rewardMessage;
          const char* rewardItem;
          int rewardAmount;
      };
      const paramList* params = (paramList*)systemData;
  
      //Rewarded Ad Completed with parameters:
      //preroll message: params->preMessage
      //reward message: params->rewardMessage
      //reward item: params->rewardItem
      //reward amount: params->rewardAmount
  
      return 1;
  }

The data received through systemData parameter is as follows;

  • preMessage (char): The message displayed when the reward is offered (before the rewarded video starts playing)
  • rewardMessage (char): The message displayed when the reward is granted (when the rewarded video is completed)
  • rewardItem (char): Rewarded Virtual Currency Type
  • rewardAmount (int): Rewarded Virtual Currency Amount

Once the ad is closed by the user, the FUSESDK_AD_WILL_CLOSE callback will be received.

IAP and Virtual Good Offers

If you are displaying ads with an IAP or Virtual Good offer and the user has accepted an offer, FUSESDK_IAPOFFER_ACCEPTED or FUSESDK_VIRTUALGOODSOFFER_ACCEPTED callback will be received.

  int32 IAPOfferAccepted(void* systemData, void* userData)
  {
      struct paramList
      {
          float productPrice;
          int itemAmount;
          const char* itemName;
          const char* productID;
      };
      const paramList* params = (paramList*)systemData;
  
      //IAPOfferAccepted with parameters:
      //product price: params->productPrice
      //item amount: params->itemAmount
      //item name: params->itemName
      //product ID: params->productID
  
      return 1;
  }

The data received through systemData parameter when an IAP Offer has been accepted is as follows;

  • productID (char): ID of the offered item
  • productPrice (float): Price of the IAP (0 or the value in local currency if available eg. 2.99)
  • itemName (char): Name of the offered item
  • itemAmount (int): Quantity of items shown on the offer
  int32 VGOfferAccepted(void* systemData, void* userData)
  {
      struct paramList
      {
          const char* purchaseCurrency;
          float purchasePrice;
          const char* itemName;
          int itemAmount;
      };
      const paramList* params = (paramList*)systemData;
  
      //VGOfferAccepted with parameters:
      //purchase currency: params->purchaseCurrency
      //purchase price: params->purchasePrice
      //item name: params->itemName
      //item amount: params->itemAmount
  
      return 1;
  }

The data received through systemData parameter when a Virtual Good Offer has been accepted is as follows;

  • purchaseCurrency (char): The currency shown on the offer
  • purchasePrice (float): The price shown on the offer
  • itemName (char): Name of the offered item
  • itemAmount (int): Quantity of items shown on the offer

Once the offer is closed by the user, the FUSESDK_AD_WILL_CLOSE callback will be received.

Tracking In App Purchases

NoteBubble.png

Before your app goes live you must set up Google In-App Purchase Validation through FusePowered Dashboard (see below)

NoteBubble.png

When registering in-app purchases, especially when testing IAP offers, make sure to use a US based iTunes account. Our system uses USD prices by default.

Fuse allows tracking of in-app purchases in real-time. To do this, use the following calls:

iOS

To register the price and currency that a user is using to make iOS in-app purchases, use the method FuseSDKRegisterInAppPurchaseiOS;

  FuseSDKRegisterInAppPurchaseiOS(purchaseState, receiptData, recieptDataLength, price, currency, productID, transactionID);

Call this function directly after an in-app purchase is made once it has been confirmed that the transaction has occurred successfully.

The arguments passed on to this method are;

  • purchaseState (FusePurchaseState): An object set to the purchase details for easy parsing by the fuse system (PURCHASED=0, CANCELED=1, REFUNDED=2)
  • receiptData (char): The receipt from the purchase transaction
  • recieptDataLength (int): the size of the receipt data
  • price (double): Purchase price.
  • currency (char): Currency code
  • productId (char): The product identifier
  • transacationID (char*): The transaction ID of the purchase

Android

To record an Android in-app purchase in the Fuse system, use the FuseSDKRegisterInAppPurchaseAndroid method;

  FuseSDKRegisterInAppPurchaseAndroid(purchaseState, purchaseToken, productId, orderId, purchaseTime, developerPayload, price, currency);	

Call this function directly after an in-app purchase is made once it has been confirmed that the transaction has occurred successfully.

The arguments passed on to this method are;

  • purchaseState (FusePurchaseState): An object set to the purchase details for easy parsing by the fuse system (PURCHASED=0, CANCELED=1, REFUNDED=2)
  • purchaseToken (char): The token from the purchase transaction
  • productId (char): The product identifier
  • orderId (char): The order identifier
  • purchaseTime (long): Timestamp of the purchase
  • developerPayload (char): Developer payload from the purchase
  • price (double): Purchase price.
  • currency (char): Currency code

The Callback

Once the method has been called, the FUSESDK_AD_WILL_CLOSE callback will be received.

  int32 PurchaseVerified(void* systemData, void* userData)
  {
      struct paramList
      {  
          int verified;
          const char* transaction_id,
          const char* original_transaction_id;
      };
      const paramList* params = (paramList*)systemData;
  
      //PurchaseVerified with parameters:
      //verified: params->verified
      //transaction id: params->transaction_id
      //original transaction id: params->original_transaction_id
  
      return 1;
  }

The data received through systemData parameter when this call is made is as follows;

  • verified (int): Whether the IAP has been verified (1 for verified, 0 for not verified, or -1 for could not verify)
  • transaction_id (char): Transaction ID of the IAP
  • original_transaction_id (char): Original transaction ID of the IAP

transaction_id and original_transaction_id are the same in all cases except when restoring a previous transaction. When restoring a previous transaction, transaction_id is the id of the transaction that is restoring the purchase, and original_transaction_id is the id of the original purchase.

Tracking Player Level and Currencies

To register an amount of currency for a user, use the FuseSDKRegisterCurrency method.

  FuseSDKRegisterCurrency(currencyType, balance);

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

Fuse can also track player levels using the FuseSDKRegisterLevel method.

  FuseSDKRegisterLevel(level);

Where the level parameter is the user's current level (int).

Both of these calls are important because Currency and Level data can be used to create segments. When you implement these Specific Events, you can make segments based on player levels and currency data.

Push Notifications

iOS

On iOS, FuseSDK registers for push notifications automatically when the session has been started, if the app's provisioning profile supports push notifications.

Android

NoteBubble.png

Please refer to this page to set up GCM before enabling Fuse SDK Push notification features for Android devices.

To enable push notifications for Android, you need to make the following change in your manifests;

  • Edit FuseSDK/source/android/ExtraManifests.txt, replace com.fusepowered.marmaladesample with your application bundle ID

After starting a session, you need to make the following call to register for push notifications;

  FuseSDKRegisterForPushNotifications("GCM Project ID");

The argument passed on to this method is the Project Number obtained after registering for GCM through Google's portal.