Kiip Android SDK

Overview

Read up on the various features and aspects of the Kiip Android SDK. For a step-by-step guide, please check out the Android Guide.

Javadocs

For advanced integrations you may prefer browsing the complete set of auto-generated Javadocs. If you have any questions about methods or classes mentioned and not outlined below please feel free to contact us.

Initialize

Once you register an Android app on our application dashboard, we’ll automatically generate an App Key and App Secret–keep them handy when you start the initialization process. Generally, you’ll initialize the Kiip SDK within your Application’s Application class method onCreate.

The method to initialize the Kiip SDK takes the following parameters:

  • @param context (Application): The application context. Typically this.
  • @param appKey (String): Your application key, provided by Kiip.
  • @param appSecret (String): Your application secret, provided by Kiip.
Kiip.init(context, "app_key", "app_secret");

me.kiip.sdk.Kiip is the only required import from Kiip when initializing.

Lifecycle

Kiip’s startSession and endSession calls must be called on every onStart and onStop method you implement in your activities.

Kiip startSession

Tells the Kiip SDK to start a session.

  • @param callback (Kiip.Callback): Callback that has onFinished and onFailed methods
Kiip.getInstance().startSession(new Kiip.Callback() {
    ...
});

Kiip endSession

Tells the Kiip SDK to end a session.

  • @param callback (Kiip.Callback): Callback that has onFinished and onFailed methods
Kiip.getInstance().endSession(new Kiip.Callback() {
    ...
});

Moments

When you save a moment with the SDK, it’s automatically registered with us on the dashboard. You will need to make sure the Kiip.Callback() is up and running, to handle error.

Save a moment

  • @param momentId (String): The unique identifier of the moment. This will dynamically create a moment for tracking in the Kiip system. This is an arbitrary name chosen by you.
  • @param callback (Kiip.Callback): A callback that must be created to handle the onFailed and onFinished methods.
Kiip.getInstance().saveMoment( "Beat Level One", new Kiip.Callback() {
    @Override
    public void onFinished(Kiip kiip, Poptart poptart) {
        // KiipFragmentCompat.showPoptart(poptart)
        // or, onPoptart(poptart)
    }

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

KiipFragmentCompat

The Kiip SDK has built-in support for Android fragments. The recommended way to initialize the Kiip view manager is by doing the following in your onCreate:

if (savedInstanceState != null) {
    mKiipFragment = (KiipFragmentCompat) getSupportFragmentManager().findFragmentByTag(KIIP_TAG);
} else {
    mKiipFragment = new KiipFragmentCompat();
    getSupportFragmentManager().beginTransaction().add(mKiipFragment, KIIP_TAG).commit();
}

You can then show a Poptart by doing:

mKiipFragment.showPoptart(poptart);

Object Properties

The Kiip object allows you to attach user information automatically without user intervention. For example, if you already have a user’s e-mail, you can pre-populate a reward unit when you reward your users.

Object

Set the following properties on Kiip.getInstance().

Email

Pre-populate the email field for the user.

  • @param email (String): Set the users email address
Kiip.getInstance().setEmail("support@kiip.me");

userId

Pre-populate the email field for the user.

  • @param userId (String): Set the user ID
Kiip.getInstance().setUserId("4053012");

Gender

Set the users gender for better reward targeting.

  • @param gender (String): Set the users gender. E.g. “male” or “female”.
Kiip.getInstance().setGender("female");

Birthday

Set the users birthday for better reward targeting.

  • @param birthday (String): Set the users birthday.
Kiip.getInstance().setBirthday("06/27/91");

Poptart Overview

Poptart is the name of the entire reward workflow Kiip manages for you. By calling onPoptart when you save a moment, Kiip enables the following routine to run:

saveMoment called > Poptart onShow > Modal onShow > Modal onDismiss > Poptart onDismiss

Event Listeners

Kiip’s SDK can notify you of events that occur. Within the BaseFragmentActivity class, you can set listeners for:

  • poptarts
  • modals
  • video playback
  • virtual currency

Poptarts onShow

Called when the reward workflow starts.

@Override
public void onShow(Poptart poptart) {
   Log.d(tag, "poptart onShow called");
}

Poptart onDismiss

Called when the entire reward workflow has ended.

@Override
public void onDismiss(Poptart poptart) {
   Log.d(tag, "Poptart onDismiss called");
}

Called when a full screen interstitial appears.

@Override
public void onShow(Modal modal) {
   Log.d(tag, "Modal onShow called");
}

Called when a full screen interstitial disappears.

@Override
public void onDismiss(Modal modal) {
   Log.d(tag, "Modal onDismiss called");
}

Video onVideoWillPlay

Called when a video reward will play.

Video onVideoStopped

Called when a video is finished (via user or completion).

Virtual Currency

To enable virtual currency you will need to create a currency listener and let Kiip know you can take virtual rewards. This listener will be called every time a virtual reward is served and the user redeems it.

Kiip.OnContentListener onContent = 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(onContent);

Reward Redemption Callback URL

If you choose to validate a reward redemption you may via a server callback. First you will have to set up a callback URL. This requires creating an endpoint on an accessible server.

When a user redeems a reward, the Kiip servers will immediately POST a request to the callback URL specified in your setup.

The POST request will contain the following data:

  • transaction_id (string): The unique reward transaction ID.
  • signature (string): The signed signature of the payload. Used to verify valid posts. See below for more information.

Verify a redemption callback using this string containing the following:

sha1(transaction_id + app_secret)

Here’s a quick example of how you would verify the request in python:

def is_valid_request(transaction_id, signature):
    sign = '%s%s%s' % (user_id, transaction_id, YOUR_APPLICATION_SECRET)
    return hashlib.sha1(sign).hexdigest() == signature

Virtual Currency Reward Redemption Callback URL

The same callback URL can be used to verify a virtual currency reward redemption. This callback does require a userId be set on the Kiip object.

The POST request will contain the following data:

  • content (string): The unique identifier of the virtual currency (e.g. coins)
  • quantity (int): The quantity of the virtual currency (e.g. 20)
  • user_id (string): The User ID specified to the Kiip Web SDK. Virtual currency will be applied to this User ID.
  • transaction_id (string): The unique reward transaction ID.
  • signature (string): The signed signature of the payload. Used to verify valid posts. See below for more information.

Verify a virtual currency callback using this string containing the following:

sha1(content + quantity + user_id + transaction_id + app_secret)

Here’s a quick example of how you would verify the request in python:

def is_valid_request(content, quantity, user_id, transaction_id, signature):
    sign = '%s%s%s%s%s' % (content, quantity, user_id, transaction_id, YOUR_APPLICATION_SECRET)
    return hashlib.sha1(sign).hexdigest() == signature

Native Rewards

Native Rewards offer more control over how Kiip rewards display. In most cases, Native Rewards are used to control display positioning. Containers designated for a Native Rewards must be 300px by 250px.

To enable Native rewards in the ListView widget, initialize KiipRewardAdapter and set it to setAdapter of ListView widget with the position to show the Kiip Reward Unit.

private ListView mListView;
private KiipRewardAdapter mKiipRewardAdapter;

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

    ArrayAdapter<String> listAdapter = new ArrayAdapter<String>(getActivity(), android.R.layout.simple_list_item_1);

    // KiipRewardAdapter will be used in place of the original adapter for the ListView.
    mKiipRewardAdapter = new KiipRewardAdapter(this, listAdapter, 2);
    mKiipRewardAdapter.saveMoment("<MOMENT_ID>");

    // Set the KiipRewardAdapter object on the ListView.
    listView.setAdapter(mKiipRewardAdapter);
}

Custom Notifications

The Kiip SDK allows you to attach your own assets when you show a notification view. This promotes a higher level of immersion for your app’s UX. Step one is to ensure you are saving moments correctly. Once that’s taken care of, navigate to your saveMoment callback.

You’ll want to start by listening in on the poptart.onShow method. Once that’s taken care of, you can begin to construct your own notification view, and attach it to the poptart:

// within poptart.onShow
// create your custom notification.

poptart.setNotification( /* your customly created notification */ );
return poptart;

Once you’ve created your new poptart with your custom notification, every time you call saveMoment with the completionHandler, you can do onPoptart(poptart).

Example

Check out the notification below to get an idea of what a custom notification can look like (You earned a reward! section):

Example reward

Note: There is more than one right way of implementing custom notifications.