Jump to: navigation, search

Android

Revision as of 17:10, 2 October 2018 by Akokulu (Talk | contribs) (Importing)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Android 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 refer to this page for the FuseSDK Code Reference.

Importing

The Fuse SDK is distributed through a maven repository. To use it, add the following to your project's build.gradle file:

  allprojects {
    repositories {
      jcenter()
      maven {
        url  "https://nexus.upsight.com/nexus/content/repositories/upsight-android-release/"
      }
    }
  }

Next, add the following to your app's build.gradle file:

  dependencies {
    compile 'com.upsight.android:mediation-core:2.12.2'
  }

Setting up the Manifest

NoteBubble.png

The minimum supported target is API level 16

By adding FuseSDK as a dependency through gradle, most of the manifest entries will be automatically included for you. There are some additions, however, that may be necessary.

Location

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

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

In App Billing

If you intend to use IAPs/offers in your app, make sure to include the billing permission:

    <uses-permission android:name="com.android.vending.BILLING" />

SSL

In order to support SSL (secure socket layer) and force all Fuse data connections to work over https, add the following to your manifest file:

     <meta-data android:name="com.upsight.mediation.usessl" android:value="true" />

Push Notifications

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

        <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
        <permission android:name="[APPLICATION PACKAGE].permission.C2D_MESSAGE" android:protectionLevel="signature" />
        <uses-permission android:name="android.permission.GET_ACCOUNTS" />
        <receiver
            android:name="com.upsight.mediation.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.upsight.mediation.push.FuseIntentService" />
  
        <activity
            android:name="com.upsight.mediation.push.FuseRecordGCMResponse"
            android:configChanges="keyboardHidden|orientation"
            android:label="FuseRecordGCMResponse">
        </activity>


NoteBubble.png

The Google Play Services and Android Support v4 libraries will be included automatically as they are dependencies of Fuse SDK.

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

Using The SDK

Import Statements

Before we start making calls with the Fuse SDK we need to import some tools first. The import statements should look like this:

 import com.upsight.mediation.*;
 import com.upsight.mediation.util.*;

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.

 @Override
 public void onCreate(Bundle savedInstanceState) {
    final Context appContext = getApplicationContext();
    final FuseSDKListener fuseListener = new FuseSDKListener(){
        ...
    }

    FuseSDK.init("<UNIQUE APP ID>", this, null, fuseListener); 
 
 } 

The Parameters of this call are:

  • appId: The app ID is found under the app name in the dashboard.
  • mainActivity: the activity making the call (this)
  • options: Start Session Options (can be null)
  • listener: an implementation of the FuseSDKListener interface.

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 Listener:

After you send a request to the FuseSDK, it will respond using callback functions. When you get a callback, you can handle the event as desired. For example, when you call init(), 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 implement the FuseSDKListener interface, simply declare the following object to pass into startSession:

  final FuseSDKListener fuseListener = new FuseSDKListener() 
  { 
    @Override 
    public void sessionLoginError(FuseError error) 
    { 
        // an error has occurred 
    } 
 
    @Override 
    public void sessionStartReceived() 
    { 
    } 
 
    // other interface methods available <!-- link here -->
  }; 

init:

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

 @Override
 public void sessionStartReceived(){
    FuseSDK.showAdForZoneID("ZONE ID HERE", options);
 }

Click here for an explanation of this call

Showing Ads

NoteBubble.png

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

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("ZONE ID");

As a result of this call, the [adAvailabilityResponse] listener function will be called:

  @Override 
  public void adAvailabilityResponse(boolean available, String adZone, int error) 
  {
   
     if (error > 0)
     {
         // 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

Use the following method for displaying ads;

  FuseSDK.showAdForZoneID("ZONE ID", options);

Once the ad is closed by the user, control will be passed back to the application through the adWillClose callback method (implemented in your FuseSDKListener object). 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.

Rewarded Ads

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

  FuseSDK.zoneHasRewarded("ZONE ID"); //returns boolean

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

  FuseSDK.getRewardedInfoForZoneID("ZONE ID"); //returns RewardedInfo

If you are displaying rewarded ads, in addition to adWillClose, rewardedAdCompleteWithObject callback method will be called.

   @Override 
   public void rewardedAdCompleteWithObject(RewardedInfo rewardInfo) 
   {
      
   }

RewardedInfo: The RewardedInfo object contains the following:

PROPERTY TYPE DESCRIPTION
preRollMessage String The message displayed before the video starts playing (e.g. Watch a video and earn a reward!)
rewardMessage String The message displayed when the rewarded video is completed (e.g. Congrats! You've earned a reward!)
rewardItem String The name of the reward item/currency (as defined in the Fuse dashboard)
rewardAmount Integer The amount of the rewarded item/currency
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 callback methods will be called respectively.

   @Override 
   public void IAPOfferAcceptedWithObject(OfferInfo offer) 
   {
      
   }
  
   @Override 
   public void virtualGoodsOfferAcceptedWithObject(OfferInfo offer) 
   {
      
   }

IAP OfferInfo

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

Virtual Good OfferInfo

PROPERTY TYPE DESCRIPTION
purchaseCurrency String The currency used to purchase the offer.
purchasePrice Float Price of the virtual good.
itemName String The name of the item being purchased.
itemAmount Integer Quantity of items being purchased
currencyID Integer 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 Integer 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 String Custom metadata that is associated with the offer.
startTime Date Start date of the offer as a unix epoch (GMT).
endTime Date End date of the offer as a unix epoch (GMT)

Tracking In App Purchases

NoteBubble.png

Before your app goes live you must set up Google In-App Purchase Validation via the Fuse dashboard.

IAP-Validation-Android.png

To set up IAP Validation in the Fuse dashboard:

1. From any page in the Fuse dashboard, click on your username in the top right of the upper navigation bar.

2. Choose “Store Credentials” from the dropdown menu

3. Select the “Android” tab

4. In the “IAP Validation” section, click the “GET REFRESH TOKEN” button and follow the instructions


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

 import com.upsight.mediation.FuseSDK;
 import com.upsight.mediation.util.PurchaseState;
 import com.upsight.mediation.util.VerifiedPurchase;
 
 ...
  
  public void onIabPurchaseFinished(IabResult result, Purchase info) //This method will be automatically called
  {
    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:
    FuseSDK.registerInAppPurchase(verifiedPurchase, 1.99, "USD");
  
    //Otherwise use
    FuseSDK.registerInAppPurchase(verifiedPurchase);
 }

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

Tracking Virtual Good Purchases

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

  FuseSDK.registerVirtualGoodsPurchase:198 Amount:5300 CurrencyID:12;

Note that “registerVirtualGoodsPurchase” is expecting the virtual good ID. This ID is a property of the object called OfferInfo (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(int playerLevel);

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(int currencyIndex,int currencyBalance);

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(int year, int month, int day);

Age

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

  FuseSDK.registerAge(int age);

Gender

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

  FuseSDK.registerGender(int genderIndex);

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(bool consent);

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(int eventID,int eventValue);

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

  FuseSDK.registerCustomEvent(int eventID,string eventValue);

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

NoteBubble.png

Please refer to this page to set up GCM before integrating Fuse SDK Push notification features.

To enable push notifications, you need to make the following call;

  FuseSDK.setupPushNotifications (String GCM_Sender_ID, Intent intent, int smallIconId, int largeIconId)

This method allows you to enable push notifications from Fuse. This handles registering for tokens as well as displaying and tracking notifications when received and clicked. When calling this method, the intent object parameter is cached and used in the future when a notification is opened. This allows you to specify which activity should be started from notifications. You will need to create a project for your game in the Google Developers Console and save your token on the Fuse dashboard. Refer to this page for more information.

Parameters

  • GCM_Sender_ID: This value can be found on the Google Developers Console after creating and entry for your game as part of Legacy Cloud Messaging.
  • intent: The intent that will be started when a notification is opened
  • smallIconId: a resource id for a small version of the icon used in the notification
  • largeIconId: a resource id for a large version of the icon used in the notification