Android

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 Android SDK Here.

Importing

The Fuse API contains these files:

 - Code/FuseSDK.jar
 - README.md

Once you have downloaded the files you need to import the files into your Eclipse Project File. First we need to add FuseSDK.jar as a library to the build path of the project, to do this in Eclipse:

1) Right Click the project/libs folder and select Import... from the dropdown menu

AndroidImport1.png

2) Select General > File System from the Import dialog box and press Next

AndroidImport2.png

3) Browse to the FuseSDK/Code folder

AndroidImport3.png

4) Check FuseSDK.jar and click on Finish

AndroidImport4.png

The .jar file should now be imported to your project.

Next we need to add it to the Build path libraries.

1) Right click on the project and select Build Path > Configure Build Path from the dropdown menu

AndroidImport5.png

2) In the dialog box that opens You are already in the Java Build Path page, click on the Libraries Tab

AndroidImport6.png

3) Click on the Add JARs... button and select the FuseSDK.jar file that you imported to your project and click ok.

AndroidImport7.png

4) The JAR file will be added to the library list. Press OK to close the dialog.

AndroidImport8.png

When this is complete you can import FuseAPI classes.

Set up

Project Configuration

Manifest

NoteBubble.png

The minimum supported target is API level 11

Fuse activities must be configured in the AndroidManifest.xml file. Add these activities under your application Tag.

   <meta-data 
       android:name="com.google.android.gms.version" 
       android:value="@integer/google_play_services_version" />
   <receiver
       android:name="com.fusepowered.push.FusePushNotificationReceiver"
       android:permission="com.google.android.c2dm.permission.SEND" >
       <intent-filter>
           <action android:name="com.google.android.c2dm.intent.RECEIVE" />
           <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
           <category android:name="<Application Package>" />
       </intent-filter>
   </receiver>
   <service android:name="com.fusepowered.push.FuseIntentService" />
   <activity
       android:name="com.fusepowered.push.FuseRecordGCMResponse"
       android:configChanges="keyboardHidden|orientation"
       android:label="FuseRecordGCMResponse" >
       <intent-filter>
           <action android:name="com.acme.FuseAndroidGame.fusepowered.push.FuseRecordGCMResponse" />
           <category android:name="android.intent.category.DEFAULT" />
       </intent-filter>
   </activity>
   <activity
       android:name="com.fusepowered.fuseactivities.FuseApiMoregamesBrowser"
       android:label="FuseApiMoregamesBrowser" >
       <intent-filter>
           <action android:name="com.fusepowered.fuseactivities.FuseApiMoregamesBrowser" />
           <action android:name="android.intent.action.VIEW" />
           <category android:name="android.intent.category.DEFAULT" />
       </intent-filter>
   </activity>
   <meta-data
       android:name="com.google.android.gms.version"
       android:value="@integer/google_play_services_version" />
   <activity
       android:name="com.fusepowered.m2.mobileads.M2Activity"
       android:configChanges="keyboardHidden|orientation|screenSize" />
   <activity
       android:name="com.fusepowered.m2.mobileads.M2RActivity"
       android:configChanges="keyboardHidden|orientation|screenSize" />
   <activity
       android:name="com.fusepowered.m2.common.M2Browser"
       android:configChanges="keyboardHidden|orientation|screenSize" />
   <activity
       android:name="com.fusepowered.m2.mobileads.M2RvpActivity"
       android:configChanges="keyboardHidden|orientation|screenSize" />
   <activity
       android:name="com.fusepowered.m1.android.MMActivity"
       android:configChanges="keyboardHidden|orientation|keyboard"
       android:theme="@android:style/Theme.Translucent.NoTitleBar" />
   <activity
       android:name="com.fusepowered.m1.android.VideoPlayer"
       android:configChanges="keyboardHidden|orientation|keyboard" />
   <activity
       android:name="com.fusepowered.u1.U1InterstitialActivity"
       android:configChanges="keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize"
       android:hardwareAccelerated="true"
       android:theme="@android:style/Theme.NoTitleBar.Fullscreen" />
   <activity
       android:name="com.fusepowered.s1.S1InterstitialActivity"
       android:hardwareAccelerated="true" />
   <activity
       android:name="com.vungle.sdk.VungleAdvert"
       android:configChanges="keyboardHidden|orientation|screenSize"
       android:theme="@android:style/Theme.NoTitleBar.Fullscreen" />
   <service android:name="com.vungle.sdk.VungleIntentService" />
   <activity
       android:name="com.fusepowered.ads.adapters.FuseInterstitialActivity"
       android:configChanges="keyboardHidden|orientation|screenSize"
       android:noHistory="true"
       android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen" />
   <activity
       android:name="com.fusepowered.l1.AdActivity"
       android:configChanges="orientation|keyboardHidden|screenSize"
       android:hardwareAccelerated="true" />
   <activity android:name="com.fusepowered.l1.AdBrowserActivity" />
   <activity
       android:name="com.fusepowered.l1.PlayerActivity"
       android:configChanges="orientation|keyboardHidden|screenSize"
       android:hardwareAccelerated="true" />
   <activity
       android:name="com.fusepowered.ac.ACOActivity"
       android:configChanges="keyboardHidden|orientation|screenSize"
       android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen" />
   <activity
       android:name="com.fusepowered.ac.ACFActivity"
       android:configChanges="keyboardHidden|orientation|screenSize"
       android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen" />
   <activity
       android:name="com.fusepowered.ac.ACBActivity"
       android:configChanges="keyboardHidden|orientation|screenSize"
       android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen" />
   <activity
       android:name="com.fusepowered.ads.adapters.LRActivity"
       android:configChanges="keyboardHidden|orientation|screenSize"
       android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen" />
   <activity
       android:name="com.fusepowered.ads.adapters.MRaidActivity"
       android:configChanges="orientation|keyboard|keyboardHidden|screenLayout|screenSize"
       android:hardwareAccelerated="true"
       android:theme="@android:style/Theme.Translucent.NoTitleBar"
       android:windowSoftInputMode="adjustResize" />
   <activity
       android:name="com.fusepowered.ads.adapters.MRaidVideoActivity"
       android:configChanges="orientation|keyboard|keyboardHidden|screenLayout|screenSize"
       android:hardwareAccelerated="true"
       android:theme="@android:style/Theme.Black.NoTitleBar"
       android:windowSoftInputMode="adjustResize" />
   <activity
       android:name="com.fusepowered.sa.android.publish.list3d.List3DActivity"
       android:theme="@android:style/Theme" />
   <activity
       android:name="com.fusepowered.sa.android.publish.AppWallActivity"
       android:configChanges="orientation|keyboardHidden|screenSize"
       android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen" />
   <activity
       android:name="com.fusepowered.as.view.ASVastInterstitialActivity"
       android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize"
       android:theme="@android:style/Theme.Translucent" />
   <activity
       android:name="com.fusepowered.as.view.ASWebviewInterstitialActivity"
       android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize" />
   <activity
       android:name="com.fusepowered.ap.MainActivity"
       android:configChanges="orientation|screenSize"
       android:exported="false"
       android:theme="@android:style/Theme.Translucent" />
   <activity
       android:name="com.fusepowered.ap.BrowserActivity"
       android:configChanges="orientation|screenSize" />
   <activity
       android:name="com.fusepowered.ap.VDActivity"
       android:configChanges="orientation|screenSize"
       android:screenOrientation="landscape"
       android:theme="@android:style/Theme.NoTitleBar.Fullscreen" >
   </activity>
   <activity
       android:name="com.fusepowered.al.ALInterstitialActivity"
       android:configChanges="orientation|screenSize" />
   <activity
       android:name="com.fusepowered.al.ALConfirmationActivity"
       android:configChanges="orientation|screenSize" />
   <activity
       android:name="com.fusepowered.im.androidsdk.IMBrowserActivity"
       android:configChanges="keyboardHidden|orientation|keyboard|smallestScreenSize|screenSize"
       android:hardwareAccelerated="true"
       android:theme="@android:style/Theme.Translucent.NoTitleBar" />

Other Configuration Changes

The following permissions are needed to be able to use the Fuse SDK. They should be added to the AndroidManifest.xml file if they are not already there.

   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
   <uses-permission android:name="com.android.vending.BILLING" />
   <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
   <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
   <permission android:name="<Application Package>.permission.C2D_MESSAGE" android:protectionLevel="signature" />

The following permissions are optional but can greatly improve ad performance.

   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

The following permissions are required only if you are using C2DM (Push Notifications)

   <uses-permission android:name="android.permission.GET_ACCOUNTS" />


NoteBubble.png

You must also add Google Play Services and the Android v4 support library to your project as an Android library project dependency. See Here for a guide on Google Play Services and Here for the support library.


Once this is complete, you will be able to compile your project with the Fuse SDK included.

Import Statements

Before we start making calls with the Fuseboxx™ SDK we need to import some tools first. The Fuse files to be imported are all in the com/fusepowered directory provided with the SDK. The import statements should look like this:

import com.fusepowered.fuseactivities.*;
import com.fusepowered.fuseapi.*;
import com.fusepowered.util.*;
import com.fusepowered.activities.*;

import android.content.Context;

You need to import android.content.Context so you can use AppContext when messaging the Fuse System.

Starting a Session

The most important function call is to register the start of an app session. The FuseBoxx™ servers identify the app using the "UNIQUE API KEY" that was generated for your app in the dashboard.

@Override
public void onCreate(Bundle savedInstanceState) {
   final Context appContext = getApplicationContext();
   final MessageCallback startSessionCallback = new MessageCallback(this){
       ...
   }

   FuseAPI.startSession("<UNIQUE API KEY>", this, appContext, startSessionCallback); 

} 

The Parameters of this call are:

game_id(APIkey): your app's API key (see Your API Keys page on FuseBoxx™)

activity_object: the activity making the call (this)

application_context: the application context (getApplicationContext())

MessageCallback: an object which is an instance of a class that extends the abstract class FuseCallback.java - You can also pass null. By extending the fuseCallback.java class you can implement the abstract methods.

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). For example, in the main page of FuseBoxx™, the sessions per user KPI provides a means of gauging retention.

The Callback:

After you send a request to the FuseAPI, the FuseAPI will respond using callback functions. When you get a callback, you can handle the event as desired. For example, when you call startSession(), the corresponding callback is sessionStartReceived. You can override the function and handle the event anyway you want. As an example, you might want to show notifications or ads. To create a FuseCallback, simply declare the following object to pass into startSession:

 final MessageCallback startSessionCallback = new 
 MessageCallback(this) 
 { 
   @Override 
   public void sessionLoginError(int arg0) 
   { 
       // an error has occurred 
   } 

   @Override 
   public void sessionStartReceived() 
   { 
   } 

   // other abstract methods available 
 }; 

The delegate protocol defines the previous functions to signal the status of the sessionStart call (see FuseSDK.java file for full list of protocol functions).

startSession:

Override any of the functions and handle the event as you desire. For example, you can override the sessionStartReceived() function to display an ad:

@Override
public void sessionStartReceived(){
   FuseAPI.displayAd("", new FuseAdCallback(MainActivity.this);
}

FuseAdCallback: an object which is also an instance of a class that extends the abstract class FuseCallback.java - you can also pass a null.

suspendSession:

This function tracks each time a session has been suspended. It should be called in the onPause() method of the main activity.

 public static void suspendSession()
 
 //example
 protected void onPause(){
     FuseAPI.suspendSession();
 }

resumeSession:

This function tracks each time a session has been resumed. It should be called in the onResume() method of the main activity.

 public static void resumeSession(FuseCallback callback) {}
 
 //example
 @Override
 protected void onResume(){
     FuseAPI.resumeSession(this, new MessageCallback(this));
 }

MessageCallback: an object which is also an instance of a class that extends the abstract class FuseCallback.java - you can also pass a null.

endSession:

Should be called in the onTerminate() method of the application or onDestroy() of the main activity.

 public static void endSession() {}
 
 //example
 protected void onDestroy() { 
     FuseAPI.endSession();
 }

Showing Ads

Checking Ad Availablility

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

 FuseApi.checkAdAvailable("ad zone name", fuseAdCallbackObject);

The result will be returned to the FuseAdCallback object provided in the above call:

 public void adAvailabilityResponse(int available, int error);

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

Display Ads

In order to implement interstitial ads, an ad callback needs to be created. This allows the ad to signal your app when it has closed. This is usually done inline while calling displayAd(), but you can create a class that extends the FuseAdCallback class if you prefer.

 FuseAPI.displayAd(null, new FuseAdCallback() {
   @Override
   public void adDisplayed() {
       // An ad was displayed on screen
   }
   @Override
   public void adClicked() {
       // The user clicked on an ad
   }
   @Override
   public void adWillClose() {
       // The ad has been closed and the game can be resumed
   }
   @Override
   public void adFailedToLoad() {
       // No ad could be loaded (usually due to a connectivity problem)
   }
   @Override
   public void adWillLeaveApp() {
       // A user's click is opening another app or browser
   }
 });
 

Once the ad is closed by the user, control will be passed back to the application through the adWillClose callback method (implemented in your callback object).

Using Ad Zones

If you wish to show an ad for a specific ad zone, pass the name of that zone as a string in the first parameter of the displayAd() method. When the ad is closed, control will be passed back through the "adWillClose" callback method just like a normal ad call.

 FuseAPI.displayAd("Level Completed", callback);

To create a new ad zone, simply use the call with the string you would to use for the name of the new ad zone. Once an ad zone with a unique name has been called from the app, it will appear on the dashboard and can then be edited to reflect time and format based capping rules. For more information on ad zones, refer to the Using AdRally section of the wiki.

Push Notifications

Overview

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.

Integration

 <receiver android:name="com.fusepowered.push.FusePushNotificationReceiver" 
            android:permission="com.google.android.c2dm.permission.SEND" >
          <intent-filter>
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
            <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
            <category android:name="<Application Package>" />
          </intent-filter>
 </receiver>

NoteBubble.png

Set Up and Integration of Push Notifications on Android is covered in Google Cloud Messaging Setup.

Tracking In App Purchases

NoteBubble.png

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

Register IAP Call

FuseBoxx™ allows developers to track in-app purchases in real-time. To do this, use the following code block:

import com.fusepowered.fuseapi.FuseAPI;
import com.fusepowered.util.PurchaseState;
import com.fusepowered.util.VerifiedPurchase;

...
 
 public void onIabPurchaseFinished(IabResult result, Purchase info) 
 {
   VerifiedPurchase verifiedPurchase = new VerifiedPurchase(Integer.toString(info.getPurchaseState()),
      info.getToken(), info.getSku(), info.getOrderId(), info.getPurchaseTime(), info.getDeveloperPayload());
 
   //If you know the price and currency then use this:
   FuseAPI.registerInAppPurchase(verifiedPurchase, 1.99, "USD");
 
   //Otherwise use
   FuseAPI.registerInAppPurchase(verifiedPurchase);
}

A com.fusepowered.util.VerifiedPurchase object should be passed to the registerInAppPurchase method.

Google In-App Purchase Validation

Before your app goes live you must enable the validation functionality for Google Play. This is done in 3 steps and requires a login.

Step 0) Visit FuseBoxx™'s Account Services page and Scroll down to Google In-App Purchase Validation.

Collect Token.png

Step 1) Click the Collect Token button.

Step 2) Log into your Google account (remember to select the account used to publish your apps)

Step 3) Click the Authorize button to give FuseBoxx™ offline access.

You will then be directed back to FuseBoxx™. If successful, the Collect Token button will be replaced with a Refresh Token button.

GoogleAuthorizeDone.png


Tracking Player Level and Currencies

To register an amount of currency for this player, use the following function call.

 FuseAPI.registerCurrency(2, 115);

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

FuseBoxx™ can also track player levels using the following call.

FuseAPI.registerLevel(5);

Both of these calls are very handy because Currency and Level data can be used to create cohorts (i.e. if you implement these Specific Events, you could make cohorts based on player levels and currency data (which you couldn't do if you tracked only tracked these values using the Event-Parameter-Variable system)).

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:

 String *my_val = FuseAPI.getGameConfigurationValue("my_key");

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

 Dictionary<String, String> 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 = false;
 -(void) gameConfigurationReceived
 {
   has_game_config_returned = true;
      
   // You can now access your updated server-side data, either here or somewhere else in your code
   HashMap<String, String> my_vals = FuseAPI.getGameConfiguration();
   if (my_vals != null && my_vals.size() > 0)
     {
       Set<String> keySet = my_vals.keySet();
       String[] keys = (String[]) keySet.toArray();
       for( int i = 0; i < keys.length; i++ )
         {
           String key = keys[i];
           String value = my_vals.get(key);
       
           Log.d(TAG, "Key: " + key + ", Value: " + 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.