Jump to: navigation, search

IOS

iOS Integration

NoteBubble.png

Important: Please test your integration on a device. Fuse features, including AdRally 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 the iOS SDK here. You can refer to this page for the FuseSDK Code Reference.

The Fuse SDK contains the following files:

 - Code/FuseVungleAdapter.framework
 - Code/FuseSDK.h
 - Code/FuseSDKDefinitions.h
 - Code/libAdapterAdcolony.a
 - Code/libAdapterAppLovin.a
 - Code/libAdapterMopub.a
 - Code/libAdapterIronSource.a
 - Code/libAdapterUnityAds.a
 - Code/libAdapterVungle.a
 - Code/libFuseSDK.a

Importing

After downloading, import the Fuse SDK into your project. Right Click YourProject > Add Files to "YourProject".

Import1.png


Next browse to the location where you have uncompressed the SDK and select FuseSDK, on the same dialog, choose "Create groups". Now click "Add".

Importing.png


Once finished, your project should look like this

Importing2.png

NoteBubble.png

It is highly recommended to keep our adapter libraries as part of your project to ensure optimal performance from Fuse.

If your project targets both iPhone and iPad, be sure the library is included in both targets when adding it.

Once this is complete you can add the following line of code in your application or pre-compiled header:

  #import "FuseSDK.h"


Project Configuration

Required Frameworks

LinkLibraries.png

The Fuse SDK requires these frameworks to be included:

  1. Accelerate.framework
  2. AdSupport.framework (weak link)
  3. AudioToolbox.framework
  4. AVFoundation.framework
  5. CoreGraphics.framework
  6. CoreLocation.framework
  7. CoreMedia.framework
  8. CoreMotion.framework
  9. CoreTelephony.framework
  10. EventKit.framework
  11. EventKitUI.framework
  12. Foundation.framework (weak link)
  13. GameKit.framework
  14. GLKit.framework
  15. iAd.framework
  16. Javascriptcore.framework
  17. libsqlite3.dylib
  18. libxml2.dylib
  19. libz.dylib
  20. MediaPlayer.framework
  21. MessageUI.framework
  22. MobileCoreServices.framework
  23. QuartzCore.framework
  24. Social.framework (weak link)
  25. StoreKit.framework (weak link)
  26. SystemConfiguration.framework
  27. Twitter.framework
  28. UIKit.framework (weak link)
  29. UserNotifications.framework (weak link)
  30. WebKit.framework (weak link)

Additionally, the static adapters you included in your project should be listed here as well;

  1. libAdapterVungle.a
  2. libAdapterAdcolony.a
  3. libAdapterAppLovin.a
  4. libAdapterMopub.a
  5. libAdapterIronSource.a
  6. libAdapterUnityAds.a

In order to include an existing framework, navigate to the target properties of your build. Select 'Build Phases', then expand 'Link Binary with Libraries' and press the '+' to add an item.
On the pop-up screen, select the frameworks to be added.

NoteBubble.png

Fuse SDK is built using the iOS 10 SDK under Xcode 8. Using this SDK with previous versions of Xcode currently does not function. If you are using FuseSDK 2.7 or higher please build against iOS 10 using Xcode 8 or greater. Fuse SDK version 2.7 or higher will only work on devices running iOS 8 or above.
LinkerFlags.png

Linker Flags

You will also need to add the "-ObjC" flag to your "Linker Flags" section . To accomplish this, view your target properties and choose 'Build Settings'. Select the "Build" tab and find the "Other Linker Flags" entry in the "Linking" section. Be sure that the "Configuration" drop down box is set to "All Configurations". Add "-ObjC" to the settings.

NoteBubble.png

If you find you have a conflict with any ad network due to already having included their standalone SDKs, you can remove their corresponding static libraries. Otherwise, you should keep them as part of your project for optimal performance.

Privacy Settings

With the release of iOS10, Apple made it a requirement to define the usage description for references to classes that are associated with permission-related objects. For the submitted app to be approved, the following entries must be added to your Info.plist;

<key>NSCalendarsUsageDescription</key>
<string>Advertisement would like to create a calendar event.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Advertisement would like to store a photo.</string>
<key>NSCameraUsageDescription</key>
<string>Advertisement would like to use your camera.</string>
<key>NSMotionUsageDescription </key>
<string>Advertisement would like to use motion for interactive ad controls</string>


Once these steps have been completed you can begin feature integration.

App Transport Security

This feature is designed to improve the security of connections between apps and web services. Fuse mediates several third-party ad network SDKs, and some ad providers provide better performance when this feature is disabled. Please see "Support for iOS 9+" for details on how to do this.

Using The SDK

Starting a Session

Once you have added the library to your project, you can begin using it by calling the startSession function with your application's APP ID. This should be called early in the applicationDidFinishLaunching function in your application delegate.

Your APP ID is a 36-digit unique ID generated when you add your app to the Fuse Dashboard. It can be found under the title of your app on the dashboard.

To start the session, you need to call [FuseSDK startSession:delegate:withOptions:]. The delegate can be used to receive callbacks to know when the session is registered with the server, as well as other information. If the delegate is set to nil, which is possible, you won't see any callbacks sent to your application, and is therefore not recommended.

NoteBubble.png

FuseSDK expects the Application to have a keyWindow before a session start is completed, if you are having issues, please ensure your Main UIWindow is created and made key before initializing the FuseSDK.
  -(void) applicationDidFinishLaunching:(UIApplication *)application{
      ...
      [FuseSDK startSession: @"<YOUR APP ID>" delegate:yourDelegate withOptions:nil];     
      
      ...
  }
  

You can use a dictionary to hold changes to option defaults when starting a session. The defaults are defined in FuseSDKDefinitions.h, and are as follows:

/// (NSNumber*) register for push option: default @YES
extern NSString* const kFuseSDKOptionKey_RegisterForPush;

/// (NSNumber*) Optional Flag when the application requires to decide whether to open urls, including store kit urls. Useful for implementing Age Gating default @NO
extern NSString* const kFuseSDKOptionKey_HandleAdURLs;

For example, if you would like to disable automatic registration for Push Notifications, you can set the value for that key and pass it into your startSession call:

NSDictionary* session_options = [[NSDictionary alloc] initWithObjectsAndKeys:kFuseSDKOptionKey_RegisterForPush,@NO,nil];
[FuseSDK startSession: @"<YOUR APP ID>" delegate:yourDelegate withOptions:session_options];

To create a FuseDelegate object, simply declare your object as follows:

  @interface YourFuseDelegate : NSObject <FuseDelegate>
  {
  }
  
  @end


The delegate protocol defines the following functions to signal the status of the startSession call:

  @protocol FuseDelegate <NSObject>
  @required
  -(void) sessionStartReceived;
  -(void) sessionLoginError: (NSError*) _error;
  @end


Showing Ads

NoteBubble.png

Before your app goes live make sure that you've set up your zones. MORE INFO

Caching Ads

The ad networks supported through AdRally are all capable of automatically caching ads. When a Fuse session is started, a pre-computed waterfall of ad networks is sent to the Fuse SDK (based on the defined settings for the given user, and the geographic area they are in). This begins the ad network initialization process. During this process the Fuse SDK will attempt to have at least one static interstitial ad or offer (if relevant and required by at least one zone) and one video ad (again, if required by at least one zone) cached and available to be shown.

The caching process will also be started the moment an ad is consumed. Therefore, manual caching of ads is not mandatory. The simplest integration can involve only starting a session and calling for an ad.

However, for more sophisticated integrations and user experiences, it can sometimes be beneficial to preload an ad for a given zone. You can use the following function call to fetch an ad, offer, or rewarded video from the given zone and prepare it to be shown:

  [FuseSDK preloadAdForZoneID: @"<YOUR ZONE ID>"];

The result will be returned to the FuseDelegate object:

  //Example implementation of the adAvailabilityResponse callback in a FuseDelegate
  -(void) adAvailabilityResponse:(NSNumber*)_available Error:(NSError*)_error
  {
     BOOL isAvailable = [_available boolValue];
    
     int error = (int) [_error code];
    
      if (error != FUSE_ERROR_NO_ERROR)
      {
          // An error has occurred checking for the ad
      }
      else
      {
          if (isAvailable)
          {
              // An ad is available
          }
          else
          {
              // An ad is not available
          }
      }
    
  }

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 showAdForZoneID is called. If an ad is ready to be displayed, it does nothing.


Downloading an ad could take several seconds, depending on the size of the ad and connection speed. For best results, you should allow a few seconds for the ad to finish loading (after calling preloadAdForZoneID) before attempting to show it. When caching is complete through the preloadAdForZoneID call, a callback is fired which indicates whether there is an ad available or not, called adAvailabilityResponse. You can use this information to set your ad button's state enabled/disabled or visible/hidden.

For example;

  • Placement: Free currency button on the main screen of the game. Recommendation: Preload when the main screen is loaded
  • Placement: Free currency button on the store window. Recommendation: Preload when the store window is selected to load (when the store button is pressed)
  • Placement: Extra life option when the user loses their last life. Recommendation: Preload when the player starts a game with 1 life left.
  • Placement: Non rewarded ad plays before a new level starts. Recommendation: Preload immediately when the current level ends.

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.


NoteBubble.png

Please be aware that ad networks require varying amounts of time to initialize. This means that the adAvailabilityResponse callback may return false until the initialization process is complete. We therefore recommend not checking for ad availability immediately after the Fuse session start callback is triggered.


Display Ads

Once you have verified that an ad is available and that there are no errors, you can call the showAdForZoneID method.

  [FuseSDK showAdForZoneID:@"<YOUR ZONE ID>" options:nil];

Once the ad is closed by the user, control will be passed back to the application through the adWillClose delegate function (implemented in your application delegate). This function is is always fired at some point after calling showAdForZoneID, either when the ad is closed, or when no ads are loaded before timing out.

  -(void) adWillClose{
  //Continue execution flow of your application
  }

Rewarded Ads

You can check whether a zone includes rewarded content or not by calling the zoneHasRewarded method

  [FuseSDK zoneHasRewarded:@"ZONE ID"]; //returns BOOL

You can get the information on the reward by calling the getRewardedInfoForZoneID method

  [FuseSDK getRewardedInfoForZoneID:@"ZONE ID"]; //returns FuseRewardedObject

If you are displaying rewarded ads, in addition to adWillClose, rewardedAdCompleteWithObject method of the FuseDelegate object will be called.

  //Example implementation of the rewardedAdCompleteWithObject callback in a FuseDelegate
  - (void) rewardedAdCompleteWithObject: (FuseRewardedObject *) _reward
  {
  
  }

FuseRewardedObject: The FuseRewardedObject object contains the following;

  • rewardItem(NSString *): Item Name earned from the rewarded video. Set on the Dashboard.
  • rewardAmount(NSNumber *): Quantity of items earned from the rewarded video. Set on the Dashboard.
  • itemID(NSString *): the rewarded item ID as generated on the Dashboard
  • preRollMessage (NSString *): The message displayed when the reward is offered (before the rewarded video starts playing)
  • rewardMessage (NSString *): The message displayed when the reward is granted (when the rewarded video is completed)

Offers

In-app purchase and Virtual Good offers are created in the Fuse dashboard, and are then assigned to a zone. The following pages provide detailed instructions on how to set up offers in the dashboard:

You can check whether a zone includes IAP or Virtual Goods offers or not by calling the zoneHasIAPOffer method and the zoneHasVirtualGoodsOffer method respectively

  [FuseSDK zoneHasIAPOffer:@"ZONE ID"] //returns boolean
  [FuseSDK zoneHasVirtualGoodsOffer:@"ZONE ID"] //returns boolean

If you are displaying ads with an IAP or Virtual Good offer, in addition to adWillClose, the IAPOfferAcceptedWithObject method or the virtualGoodsOfferAcceptedWithObject method of the FuseDelegate object will be called respectively.

  - (void) IAPOfferAcceptedWithObject: (FuseIAPOfferObject *) _reward
  {
  
  }
  
  - (void) virtualGoodsOfferAcceptedWithObject: (FuseVirtualGoodsOfferObject *) _reward
  {
  
  }

FuseIAPOfferObject

PROPERTY TYPE DESCRIPTION
productID NSString App store product id used to complete a purchase ex. com.fusepowered.coinpack1
productPrice NSNumber Price of the IAP (in local currency if available) eg. 2.99, Default 0.
itemAmount NSNumber Quantity of items being purchased
itemName NSString The name of the item being purchased.
metadata NSString Custom metadata that is associated with the offer.
startTime NSNumber Start date of the offer as a unix epoch (GMT).
endTime NSNumber End date of the offer as a unix epoch (GMT)

FuseVirtualGoodsOfferObject

PROPERTY TYPE DESCRIPTION
purchaseCurrency NSString The currency used to purchase the offer.
purchasePrice NSNumber Price of the virtual good.
itemName NSString The name of the item being purchased.
itemAmount NSNumber Quantity of items being purchased
currencyID NSNumber The ID of the currency used for the purchase (as shown in the Fuse dashboard). Required for registering and tracking the purchase of a virtual good.
virtualGoodID NSNumber The ID of the item (virtual good) being purchased (as shown in the Fuse dashboard). Required for registering and tracking the purchase of a virtual good.
metadata NSString Custom metadata that is associated with the offer.
startTime NSNumber Start date of the offer as a unix epoch (GMT).
endTime NSNumber End date of the offer as a unix epoch (GMT)

Tracking In-App Purchases

NoteBubble.png

When registering in-app purchases, especially when testing IAP offers, make sure to use a US based iTunes account. Fuse requires USD prices by default, if the purchase is made using another currency it will be available in the Fuse dashboard for setting up targeted IAP offers.

When using Fuse to track IAPs in a native iOS application, you must first pass the response received by registering your product list to the FuseSDK method registerInAppPurchaseList.

Fetching Product List

When the product list is fetched from Apple's servers, a function needs to be called to provide the Fuse system with information on what products are available in your app. In your SKProductsRequestDelegate delegate, place the function call seen below in the productsRequest delegate function.

This must happen before purchases are registered and we suggest implementing it in the sessionStartReceived callback of your app.

  -(void)productsRequest:(SKProductsRequest*)request
    didReceiveResponse:(SKProductsResponse*) response
  {...
    [FuseSDK registerInAppPurchaseList:response];
  ...}

Register IAP Call

Once the product list has been registered, the registerInAppPurchase function needs to be called once it has been confirmed that the transaction has occurred successfully. Optimally, this should be done in the recordTransaction function in your SKPaymentTransactionObserver delegate.

  -(void) recordTransaction:(SKPaymentTransaction*)transaction{
    ...
    [FuseSDK registerInAppPurchase: transaction];
    ...
  }

Purchase Verification Callback

When an IAP is made, the Fuse server will verify the purchase with Apple's receipt validation system and notify the app using the following FuseDelegate callback:

  -(void) purchaseVerification(NSNumber*)_verified
    TransactionID:(NSString*)_tx_id
    OriginalTransactionID:(NSString*)_o_tx_id;

The _verified bit returns one of three values:

1: The purchase is suspected to be valid.

0: The purchase is suspected to be invalid.

-1: We did not attempt verification. This can be due to a network error or lack of connectivity.

Tracking Virtual Good Purchases

To track Virtual Good Purchases, use the following function call where appropriate:

  [FuseSDK registerVirtualGoodsPurchase:198 Amount:3500 CurrencyID:21];

Note that “registerVirtualGoodsPurchase” is expecting the virtual good ID. This ID is a property of the object called FuseVirtualGoodsOfferObject (property name: virtualGoodID), as is the currency ID. These IDs are generated by Fuse when virtual good and items/currencies are added to the dashboard. To find them, select your app in the dashboard, then click the "CONFIGURE" button in the top right. Click the assets tab, and the Virtual Goods sub-tab, and use the IDs as referenced in the table of virtual good entries.

Virtual-goods.png

Tracking Player Events

Player Level

To register a player's level, use the following function call where appropriate:

  [FuseSDK registerLevel:5]

Currency Balances

The Fuse Event Tracking system can also track 4 different currency balances. To register one of these balances, use the following function call:

  [FuseSDK registerCurrency:2 Balance:115];

Following registerCurrency should be a number between 1 and 4 corresponding to the currency being tracked.

Birthday

To register a player's birthday, use the following function call where appropriate:

  [FuseSDK registerBirthday:1955 Month:2 Day:24];

Age

To register a player's age, use the following function call where appropriate:

  [FuseSDK registerAge:27];

Gender

To register a player's gender, use the following function call where appropriate:

  [FuseSDK registerGender:2];

0 = None

1 = Male

2 = Female

3 = Undecided

4 = Withheld

Parental Consent

To register a player's parental consent status, use the following function call where appropriate:

  [FuseSDK registerParentalConsent:true];

Custom Player Events

Custom Player Events are used to track unique information on a per-player basis. Event numbers 1-10 are reserved for integers. To register Custom Player Events with integers, use the following function call where appropriate:

  [FuseSDK registerCustomEvent:1 withInt:42];

Event numbers 11-20 are reserved for strings. To register Custom Player Events with strings, use the following function call where appropriate:

  [FuseSDK registerCustomEvent:12 withString:@"Gryffindor"];

Some examples of things you should not track for custom integer or string-type events:

  • Device or Player IDs
  • Dynamic Variables
  • Emails
  • Account Info

Push Notifications

On iOS, FuseSDK registers for push notifications automatically on startSession, if the app's provisioning profile supports push notifications.
If you wish to register for push notifications manually instead of startSession, call startSession with the option;

kFuseSDKOptionKey_RegisterForPush,NO

At the point that you wish to register for push notifications, make the following function call;

  [FuseSDK registerForPushToken]



When a remote notification is received by the application, the FuseSDK must be notified via the applicationdidReceiveRemoteNotification method. There are two places in the AppDelegate where this method must be used:

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
  {
      NSDictionary* userInfo = [launchOptions objectForKey:UIApplicationLaunchOptionsRemoteNotificationKey];
      if( userInfo )
      {
          [FuseSDK applicationdidReceiveRemoteNotification:userInfo Application:application];
      }
  }

  - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
  {
  	[FuseSDK applicationdidReceiveRemoteNotification:userInfo Application:application];
  }