iOS

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 specific to your development environment.

  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 the iOS SDK here.

The Fuse SDK contains the following files;

- Code/libFuseSDK.a
- Code/FuseSDK.h
- Code/libFuseAdapterAdcolony.a
- Code/libFuseAdapterAppLovin.a
- Code/libFuseAdapterHyprMX.a
- Extras/Settings.bundle

Importing

After downloading the SDK, 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".

ImportFiles.png


Once finished, your project should look like this

Import ProjectLook.png


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
  3. AudioToolbox.framework
  4. AVFoundation.framework
  5. CoreGraphics.framework
  6. CoreLocation.framework
  7. CoreMedia.framework
  8. CoreTelephony.framework
  9. EventKit.framework
  10. EventKitUI.framework
  11. Foundation.framework
  12. GameKit.framework
  13. libsqlite3.dylib
  14. libz.dylib
  15. MediaPlayer.framework
  16. MessageUI.framework
  17. MobileCoreServices.framework
  18. QuartzCore.framework
  19. Social.framework (weak link)
  20. StoreKit.framework
  21. SystemConfiguration.framework
  22. Twitter.framework
  23. UIKit.framework

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.
If you are targeting your application to support an early version of iOS, you will need to weak-link the CoreTelephony.framework (before iOS 4.0) and AdSupport.framework (below iOS 6.0) in your application in order for it to compile and work properly. Change "Required" to "Optional" in the "Link Binary with Library" section of the build target.

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 AdColony, HyprMX or AppLovin due to already having included their standalone SDKs, simply remove their corresponding static libraries (libFuseAdapterAdcolony.a, libFuseAdapterAppLovin.a, libFuseAdapterHyprMX.a). Otherwise, keep these libraries as part of your project to ensure optimal performance from AdRally.

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



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 API Key. This should be called early in the applicationDidFinishLauncing function in your application delegate.

Your API key is a 36-digit unique ID generated when you add your app to AdRally. It can be found in the configuration tab of a specific game, or in the Integrate API section of AdRally.

There are two different calls to startSession (one with a FuseDelegate object reference, and one without.) The delegate can be used to receive callbacks to know when the session is registered with the server, as well as other information.

NoteBubble.png

FuseSDK expects the Application to have a key Window 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{
     ...
     [FuseAPI startSession: @"<YOUR API KEY>"];
     
     //or with the delegate
     
     [FuseAPI startSession: @"<YOUR API KEY>" Delegate:<DELEGATE REFERENCE>];
     ...
 }
 
 - (BOOL) application: (UIApplication *) application didFinishLaunchingWithOptions:(NSDictionary *) launchOptions {
     ...
 
     [FuseAPI respondToApplicationLaunchOptions:launchOptions Application:application];
 
     ...
 }

Note that if you are implementing the second function, application:didFinishLaunchingWithOptions, this function must call the logic normally contained in applicationDidFinishLaunching for the app to proceed.

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 (see FuseSDK.h file for full list of protocol functions):

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

Showing Ads

NoteBubble.png

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

Overview

It's quick and easy to start earning revenue using ads. However, to maximize your revenue, you need to know when the best time to show an ad is, and how often. We recommend tailoring ads to fit with the style of your app. If, for example, you have a game that regularly rewards users for completing tasks, you could program your ad to appear just after the player has received that reward.

Integration

Check Ad Availablility

In most circumstances you will want to check the Fuse system to see if an ad is available before displaying an Ad. You can use the following function call to perform the check:

 [FuseAPI checkAdAvailable];

the result will be returned to the FuseDelegate object:

 -(void) adAvailabilityResponse:(NSNumber*)_available
   Error:(NSNumber*)_error

From here all you have to do is check that an ad is available and that there are no errors before executing the showAdWithDelegate method.

Display Ads

In order to implement ads, an ad delegate needs to be created, so the ad can signal your app when it is closed. First, in the interface declaration of the file chosen to be the delegate, add the FuseAdDelegate parameter:

 @interface YourAdObject: NSObject <FuseAdDelegate>{
 ...
 }

Now you can invoke an advertisement by calling the following API function with an object reference to the Fuse Ad Delegate (mentioned above)

 [FuseAPI showAdWithDelegate: <FUSE AD DELEGATE REFERENCE>];

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)

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

NoteBubble.png

The SDK package also contains an optional Settings.bundle file which allows you to easily disable data collection in the configuration section of the app.

Push Notifications

Fuseboxx™ offers the ability to schedule push notifications that leverage Apple’s Push Notification Service (APNS). To use this service, the application must request a push token that is passed to the Fuse API for storage. When a new notification message is scheduled, the Fuse system will send to each device for which there is a stored token.

You can add a new Push Notification Here, but you will need to set up the appropriate Certificate first Here.

Overview

Push notifications are usually the only means that a custom message can reach the player when they are outside of the application. They are typically used for time limited sales, new updates, or even game server maintenance windows.

An additional benefit to using the Apple Push Notification Service (APNS) is that after each notification is sent, FuseBoxx™ will poll the service to find out which notification failed to send, indicating which devices the application has been deleted from. This information keeps the total number of installed application up to date, and more importantly the number of devices that can be communicated with.

Feedback on the success of the notifications, such as the number of players who immediately opened the application upon receiving the notification, and those who received it while in the application, is also available via FuseBoxx™ (and can be viewed on the (Toolboxx Tab > Push Notifications > Statistics section) Here).

Integration

To collect notification token information, the API hooks the following application calls

 -(void) application:(UIApplication *)applicationdidRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken{
   [FuseAPI applicationdidRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
 }
 
 -(void)application:(UIApplication *)applicationdidFailToRegisterForRemoteNotificationWithError:(NSError *)error {
   [FuseAPI applicationdidFailToRegisterForRemoteNotificationWithError:error];
 }
 
 -(void)application:(UIApplication *)applicationdidReceiveRemoteNotification:(NSDictionary *)userInfo {
   [FuseAPI applicationdidReceiveRemoteNotification:userInfoApplication:application];
 {

For more information on setting up Push Notifications see Setting up Apple Push Notifications or our Usage Guide on Notifications

NoteBubble.png

If you do not wish to register for push tokens immediately, there is a way to start a session without registering Push Tokens See Here

Not registering for push tokens immediately means the permission popup will not appear until you register for push tokens

If you wish to register your Push Token you can make the following function call

 [FuseAPI registerForPushToken];

Tracking In App Purchases

When using FuseBoxx™ to track IAPs in a native iOS application, you must first pass the response received by registering your product list to the FuseAPI 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
 {...
   [FuseAPI 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{
   ...
   [FuseAPI 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 Fuse Delegate 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.

NoteBubble.png

If you are also using the events system to track IAP completion, we highly suggest only registering an event if the _verified bit returns 1.

Tracking Player Level and Currencies

To register a player's level use the following syntax where appropriate:

 [FuseAPI registerLevel:5]

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

 [FuseAPI registerCurrency:2 Balance:115];

Following registerCurrency should be a number between 1 and 4 corresponding to the currency 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. There are two ways to get the data from the server, the first way is to call for a value corresponding to a specific key, as shown:

 NSString *my_val = [FuseAPI getGameConfigurationValue:@"my_key"];

and the second is to get all the parameters into a dictionary which is:

 NSMutableDictionary *my_vals = [FuseAPI getGameConfiguration];

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 FuseDelegate callback method that indicates when the values are ready to be inspected.

 Bool has_game_config_returned = NO;
 -(void) gameConfigurationReceived{
   has_game_config_returned = YES;
   NSMutableDictionary *my_vals = [FuseAPI getGameConfiguration];
   if (my_vals != nil && [my_vals count] > 0)
   {
     NSArray *keys = [my_vals allKeys];
     for (int i = 0; i < [keys count]; i++)
     {
       NSString *key = [keys objectAtIndex:i];
       NSString *value = [my_vals objectForKey:key];
       NSLog(@"Key: %@, Value :%@", key, 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.