kudosKit for Android (v1.5.4)

1. Overview

This document explains how to start using kudosKit in your Android applications.

kudosKit - Android SDK

kudosKit - Main Site

kudosKit - Developer Console

Google Play Store - Developer Console

2. First steps

2.1. Add your application to the Developer Console

  • If you haven't already, sign up and log in to the kudosKit Developer Console.
  • Add an application. Make sure that you enter your application's package name as the application's ID.
  • Your application's key should appear in the application's overview page.

2.2. Add in-app items in Google Play Store (optional)

  • Appreciation modules currently support up to 4 different in-app purchase items.
  • Each one of your applications should have its own items.
  • Item names should suggest the application they are associated with, e.g., if your application's title is "Relaxed Birds", you can prefix their names with the initials "rb": rb_kudos1, rb_kudos2, and so on.
  • Items should have a different prices, e.g., $0.99, $1.99, and so on.
  • Make sure the items are consumable.

2.3. Copy the JAR file to your project's libs directory

For example, under Linux:

$ cp kudoskit-android.jar ~/workspace/RelaxedBirds/libs

You may need to refresh your project in your IDE.

2.4. ProGuard configuration

If your project uses ProGuard, add the following lines to the proguard-project.txt file:

-keepattributes JavascriptInterface
-keepclassmembers class com.ironsrc.kudoskit.RightspotWebInterface {
  public *;
}

3. Changes to the Android Manifest

3.1. Minimum SDK version

The minimum SDK version (API level) needed to use kudosKit is 8 (Android 2.2). In your AndroidManifest.xml file you should have a line like the following:

<uses-sdk android:minSdkVersion="8" android:targetSdkVersion="16" />

3.2. Application permissions

In order to use kudosKit, your application needs certain permissions. Declare the following in your AndroidManifest.xml file:

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

You may omit the billing element if you do not have in-app items for purchase.

3.3. Rightspot activity

kudosKit uses an activity to show the appreciation modules to the user. Declare the following in your AndroidManifest.xml file:

<activity android:name="com.ironsrc.kudoskit.RightspotActivity"
          android:theme="@android:style/Theme.Translucent"
          android:configChanges="keyboardHidden|orientation|screenSize" />

If you get a String types not allowed error, you need to set the target entry in your project.properties file to API level 13 or later:

target=android-13

4. Code changes

4.1. Basic setup

In your main activity, define the following member variables:

// Your application's package name
private static final String APP_ID = "com.relaxedbirds";
// The application key from the developer console
private static final String APP_KEY = "K-123456";
// The names of the in-app items associated with your application
// You should use an empty array if you don't have in-app items to publish
private static final String[] INAPP_IDS = new String[] {
    "rb_kudos1", "rb_kudos2", "rb_kudos3", "rb_kudos4"
};
// An array of feature strings; leave empty for now
private static final String[] FEATURES = new String[] {};
// The kudosKit object (from package com.ironsrc.kudoskit)
private KudosKit mKudosKit = null;

Place the following code in your main activity's onCreate function:

mKudosKit = new KudosKit(this, APP_ID, APP_KEY);
mKudosKit.setup(FEATURES, INAPP_IDS);

Place the following line in your main activity's onStart function:

mKudosKit.onStart();

Place the following line in your main activity's onStop function:

mKudosKit.onStop();

Place the following line in your main activity's onDestroy function:

mKudosKit.onDestroy();

4.2. Does it work?

Now your application should be able to communicate with the kudosKit server. In order to check that everything is in order, run the following line of code somewhere between onStart and onStop (say, when a button is clicked):

mKudosKit.debug();

If there is a problem, we suggest that you make sure that you've used the correct application ID and key, and followed all the steps above.

If everything's OK, you can remove the call to the debug function.

4.3. Rightspots and modules

Now you're ready to choose your application's rightspots. A rightspot happens when the user of your application enters a certain situation, such as when he or she opens the application, clicks a button, passes a level, enters an activity, etc. When a rightspot happens, it won't necessarily mean that an appreciation module will be shown to the user. kudosKit will try to be smart about when to show which modules (of your choosing) and to whom.

Suppose you choose to have a rightspot when the main activity is entered. Run the following code after everything is initialized:

mKudosKit.startRightspot("App Open");

You choose the names for your rightspots. After running the code, you should be able to see the rightspot entry in your application's overview page in the Developer Console.

You can link an appreciation module (or several of them) to your rightspot using the Developer Console (but make sure to activate them). If you previously called the debug function on the device, then that particular device will always show an active module if available. Your users will not see new or changed modules until you publish your changes.

If you don't have in-app items for purchase, you should choose appreciation modules that only have social features.

Suppose you have a "Support Us" button in your application, and once clicked you want it to always show an appreciation module to a user (given that it's active and published). You can tell kudosKit to do just that in the click handler:

mKudosKit.startRightspot("Support Us", KudosKit.START_ALWAYS);

There is an issue to be aware of here. When kudosKit starts up, it fetches appreciation modules from the kudosKit server. This may take a while, and if the modules are not yet ready, and a rightspot is forced to start a module, kudosKit will show a rather plain "failsafe" module. You may want to only show (or enable) a "Support Us" button after the rightspot has been "preloaded" with a module from the server. See the Events section for more information.

4.4. Events

You may want to get notified when certain kudosKit events happen. For example, when a user has successfully purchased an in-app item.

In order to receive event notifications, you need to add an object implementing KudosKit.Listener using KudosKit.addListener:

mKudosKit.addListener(new KudosKit.Listener() {
        // Currently support for user-defined commands is not documented.
        // For now, return false.
        @Override
        public boolean rightspotCommand(String name, String arg) {
            // command not handled
            return false;
        }

        @Override
        public void onKudosKitEvent(KudosKit.EventId eventId, Object arg) {
            switch (eventId) {
            case EVENT_PRELOADED_RIGHTSPOTS:
                // rightspots got their modules ready
                enableSupportUsButton();
                break;
            case EVENT_PURCHASE_SUCCESS:
                // the user has successfully purchased an in-app item
                stopShowingAds();
                break;
            }
        }
    });

The function onKudosKitEvent receives an event identifier and an event-specific argument. The following events are documented:

IDDescriptionAdditional argument
EVENT_RIGHTSPOT_ENTEREntering a rightspot moduleRightspot name (String)
EVENT_RIGHTSPOT_EXITExiting a rightspot moduleRightspot name (String)
EVENT_PURCHASE_SUCCESSAn in-app item was purchasedIn-app item ID (String)
EVENT_PRELOADED_RIGHTSPOTSRightspots preloaded with modulesRightspot names (String[])

You can remove a listener using the KudosKit.removeListener function.

5. Anything more?

Check the Developer Console for interesting statistics about your application and your users.

More advanced use of kudosKit will be documented in later versions.

Date: 2014-02-11T15:30+0200

Author: IronSource

Org version 7.9.3f with Emacs version 24

Validate XHTML 1.0