Kiip Android Integration Guide

Introduction

This guide will walk you through adding Kiip Rewards to your Android application. Once you’re done, navigate over to the SDK Docs for more in-depth information on our SDK.

The Kiip Android SDK requires you to have an Application.class, as well as a few other details, which we will help you create below.

Getting started

First you’ll need to sign up at app.kiip.me, and grab your application key and secret.

Downloading the Kiip SDK

The latest Kiip SDK is always downloadable from the downloads page. The download also contains a helpful sample project showing off many advanced features and the actual SDK.

Adding Yourself as a Test Device

There are two ways to set Test Mode using the Kiip SDK.

1. Setting Test Mode at the build level

This Test Mode method requires Kiip SDK 2.3.0 or higher. To set Test Mode at the build level requires including the following flag:

public abstract void setTestMode(java.lang.Boolean testMode)

The default value for this flag is NO.

2. Setting Test Mode at the device level

If using this method, we recommend adding a test device to your app before getting started with integrating Kiip. However, you can add a test device in the Kiip dashboard at any time.

To add a test device to your Android app, click the Test Devices button at the bottom of the desired application page on the Kiip Dashboard. Define a unique name for the device and the device’s Google Advertising ID. This can be found in the device’s Google Settings > ads.

For Kiip Android SDK 2.0.8 or earlier, substitute the device’s Android ID for the Google Advertising ID. Use ADID Sender if you need help locating a device’s Android ID.

android test device example

Note: The Android Emulator will always will be recognized as a test device.

Common Testing Questions

What if I’m not in the US? How do I see a Kiip reward?

Test rewards fill 100% of the time, regardless of location. It is important that you add the correct device identifier inside the Test Devices section.

A null poptart? No test reward? Some devices work but others don’t!

If you’re getting a null poptart, don’t worry. This means you have correctly saved a moment through the SDK, but we didn’t recognize your device as a test device. Try the following techniques:

  • Ensure limited ad tracking is disabled in Google Settings.
  • Ensure you have copied and pasted the Google Advertising Identifier correctly.
  • Delete and re-add the correct device identifier. 2.0.9 requires Google Advertising ID, below requires Android ID.

Integrate Kiip

Adding Kiip Libraries and Resources

In the KiipSDK directory, you’ll find both a libs and res folder. You will need to drag each folder onto the Eclipse project so that you have both the Kiip library and drawables.

Adding Kiip Permissions

In your AndroidManifest.xml file, the following permissions will need to be requested in order to use the Kiip SDK:

<!-- Kiip -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<!-- END -->

<!-- Kiip Optional Permissions -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<!-- END Kiip Optional Permissions -->

<!-- Add a meta-data & provider element to the application element -->
<application android:label="@string/app_name" ...>
    ...
    <meta-data android:name="me.kiip.sdk.AppKey" android:value="@string/kiip_app_key"/>

    <provider android:name="me.kiip.sdk.KiipSDKProvider"
          android:authorities="me.kiip.sdk.KiipSDKProvider<<KIIP_APP_KEY>>"
          android:exported="true" />
    ...
</application>
<!-- END Add a meta-data & provider element to the application element -->

Application Lifecycle

The Kiip SDK intelligently manages its presence inside your application’s lifecycle, so you don’t have to. It does, however, require you to let it know whenever you start or stop an activity in your application and when your application is first created. A helper class exists to take care of all that for you.

Creating a BaseActivity Class

The best way to let the Kiip SDK know whenever a new activity in your application is started or stopped is to create an alternative Activity that all the activies extend. A sample BaseActivity.java is below:

public class BaseActivity extends FragmentActivity {
    private final static String KIIP_TAG = "kiip_fragment_tag";
    private KiipFragmentCompat mKiipFragment;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Create or re-use KiipFragment.
        if (savedInstanceState != null) {
            mKiipFragment = (KiipFragmentCompat) getSupportFragmentManager().findFragmentByTag(KIIP_TAG);
        } else {
            mKiipFragment = new KiipFragmentCompat();
            getSupportFragmentManager().beginTransaction().add(mKiipFragment, KIIP_TAG).commit();
        }
    }

    @Override
    protected void onStart() {
        super.onStart();
        Kiip.getInstance().startSession(new Kiip.Callback() {
            @Override
            public void onFailed(Kiip kiip, Exception exception) {
                // handle failure
            }

            @Override
            public void onFinished(Kiip kiip, Poptart poptart) {
                onPoptart(poptart);
            }
        });
    }

    @Override
    protected void onStop() {
        super.onStop();
        Kiip.getInstance().endSession(new Kiip.Callback() {
            @Override
            public void onFailed(Kiip kiip, Exception exception) {
                // handle failure
            }

            @Override
            public void onFinished(Kiip kiip, Poptart poptart) {
                onPoptart(poptart);
            }
        )};
    }

    public void onPoptart(Poptart poptart) {
        mKiipFragment.showPoptart(poptart);
    }
}

Note: You can also modify an existing BaseActivity to include the Kiip code.

Extending your New BaseActivity Class

After creating your new BaseActivity, all that’s left to do is edit all your other activities to extend the new class rather than the Android default.

public class MainActivity extends Activity
public class MainActivity extends BaseActivity

Application Class

If you have an Application class already, then you can skip ahead to the onCreate() portion below

The Kiip SDK requires you to have an application class and initialize Kiip in your application’s onCreate() call.

Creating an Application Class

Create a new class named App.java and have it extend Application. Something like below:

public class App extends Application {
	@Override
	public void onCreate() {
		super.onCreate();
	}
}

Now we need to add the new Application class to the AndroidManifest.xml. Modify it to add the android:name parameter in the <application> section, where the name is the name of your Application class (in this case it’s App):

<application
    android:icon="@drawable/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme"
    android:name=".App" >

Initializing Kiip in your Application’s onCreate()

Now that we have an application class, we’ll need to implement the onCreate() method and add in the Kiip initialization. Modify your onCreate() to look like this:

@Override
public void onCreate() {
    super.onCreate();
    Kiip.init(this, KIIP_APP_KEY, KIIP_APP_SECRET);
}

Call a Kiip Moment

Now that your application lifecycle is all setup, it only takes one call to send a reward to a device.

Call a Kiip moment by using the following code:

Kiip.getInstance().saveMoment(my_moment_id, new Kiip.Callback() {

    @Override
    public void onFinished(Kiip kiip, Poptart poptart) {
        if (poptart == null) {
            Log.d(KIIP_TAG, "Successful moment but no reward to give.");
        }
        else {
            onPoptart(poptart)
        }
    }

    @Override
    public void onFailed(Kiip kiip, Exception exception) {
        // handle failure
    }
});

That’s all it takes to turn any event into a Kiip moment. If you’re using the Android Emulator or a test device to call a moment, a reward should show when successfully called.

The onPoptart() call from your BaseActivity will take care of displaying fullscreen interstitial (depending on your settings).

Moment Names

Carefully consider your moment name. When you provide a title such as ‘finishing level one.’ it will be displayed to the end user when a reward is earned. The string for rewards is typically, “Congratulations! Here’s a reward for finishing level one.” This mean using an active verb such as ‘finishing’ and not ‘finished’ would be a more appropriate for a moment name.

You can always edit your moment names later in the dashboard.

Reward Virtual Currency

To enable virtual currency, create a currency listener and let Kiip know you can deliver Virtual Rewards. This listener will be called whenever a Virtual Reward is served and the user redeems it.

Kiip.OnContentListener onContentListener = new Kiip.OnContentListener() {
    @Override
    public void onContent(Kiip kiip, String momentId, int quantity, String transactionId,
            String signature) {
        // Handle receiving virtual reward. Increment users wallet with quantity etc.
    }
};

Kiip.getInstance().setOnContentListener(onContentListener);

If a user chooses not to redeem currency, then the value passed down will be zero.

Rewarded Video

Access more inventory, increase engagement and drive more revenue with Rewarded Video. To utilize Rewarded Video, designate and individual moments placement in the Kiip dashboard.

Kiip Rewarded Video Moment

Sample Application

We’ve provided a couple of sample applications for you to browse. Check out our public Github repo in case you’d like to try custom notifications, or just need to see some code samples.

Need Help?

We’re happy to answer any questions about integrating Kiip. Check out our FAQ or email us.