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).

Video onVideoFinished

Called when a video is fully viewed or completed.

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.

Currently, the reward redemption callback URL may only be used with virtual currency reward redemptions.

Virtual Currency Reward Redemption Callback URL (optional)

The 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): A unique field in which to verify the user. This could be any unique identifier, be it a login handle, email address or Advertising ID. This is required if using the virtual currency reward redemption callback.
  • 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.

ListView

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);
}

FixedView

To enable Native rewards in any view, add <me.kiip.sdk.KiipNativeRewardView/> to the layout.xml. The size of the NativeRewardView is fixed to 300x250px.

<me.kiip.sdk.KiipNativeRewardView
            android:id="@+id/kiip_native_reward_view"
            android:layout_margin="30dp"
            android:layout_width="match_parent"
            android:layout_height="match_parent"/>

//----

//And in the Activity.java or Fragment.java
private KiipNativeRewardView mRewardView;

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    ...
    ...
    mRewardView = (KiipNativeRewardView) findViewById(R.id.kiip_native_reward_view);

    //Call saveMoment in button handler or in any user interaction
    Kiip.getInstance().saveMoment("<MOMENT_ID>", new Kiip.Callback() {
        @Override
        public void onFailed(Kiip kiip, Exception exception) {
            Log.e(TAG, exception.toString());
        }

        @Override
        public void onFinished(Kiip kiip, Poptart poptart) {
            if (poptart != null) {
                //Pass the KiipNativeRewardView instance to render the native reward in the view component
                //defined in layout.xml (me.kiip.sdk.KiipNativeRewardView)
                poptart.showNativeReward(mRewardView);
            }
        }
    });
}

RecyclerView

To enable Native rewards in the RecyclerView widget, create/add linearlayout as recyclerview row like recyclerview_rewardview_row.xml and define the <me.kiip.sdk.KiipNativeRewardView/> as row component.

// recyclerview_rewardview_row.xml
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent" android:layout_height="wrap_content">

    <me.kiip.sdk.KiipNativeRewardView
        android:id="@+id/kiip_native_reward_view"
        android:layout_margin="30dp"
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>

</LinearLayout>

Follow this 6 step process in your Activity or Fragment to successfully integrate KiipNativeRewardView in RecyclerView component for e.g.,

// The RecyclerView that holds and displays Kiip Rewards.
private RecyclerView mRecyclerView;
private List<String> dataList;

@Override
public View onCreateView(final LayoutInflater inflater,
                            final ViewGroup container,
                            final Bundle savedInstanceState) {

    super.onCreateView(inflater, container, savedInstanceState);
    ...
    ...
    mRecyclerView = (RecyclerView) view.findViewById(R.id.native_recyclerview);

    RecyclerView.LayoutManager mLayoutManager = new LinearLayoutManager(getContext());
    mRecyclerView.setLayoutManager(mLayoutManager);
    mRecyclerView.setAdapter(new DataAdapter(dataList));

}

private class DataAdapter extends RecyclerView.Adapter<RecyclerView.ViewHolder> {
    
    private List<String> dataList;
    private static final int TYPE_TEXT_VIEW = 0;
    
    //1. Define ItemViewType as TYPE_REWARD_VIEW to indentify the reward row type
    private static final int TYPE_REWARD_VIEW = 1;

    public DataAdapter(List<String> dataList) {
            this.dataList = dataList;
        }

    @Override
    public RecyclerView.ViewHolder onCreateViewHolder(ViewGroup parent, int viewType) {
        //2. Inflate Reward Row
        View rewardRowView = LayoutInflater.from(parent.getContext()).inflate(R.layout.native_recycler_reward_row, parent, false);

        View listRowView = LayoutInflater.from(parent.getContext()).inflate(R.layout.native_recycler_list_row, parent, false);

        switch (viewType) {
            case TYPE_TEXT_VIEW:
                return new SimpleTextViewHolder(listRowView);
            case TYPE_REWARD_VIEW:
                //3.When ItemViewType is TYPE_REWARD_VIEW provide instanceof KiipNativeRewardViewHolder
                return new KiipNativeRewardViewHolder(rewardRowView, R.id.kiip_native_reward_view);
        }

        return null;
    }

    @Override
    public int getItemViewType(int position) {
        //4. Define in which row position we want to show the reward.
        if (position == 0)
            return TYPE_REWARD_VIEW;
        return TYPE_TEXT_VIEW;
    }

    @Override
    public int getItemCount() {
        //5. Handle the ItemCount when rewardview added.
        return (null != dataList ? dataList.size() + 1 : 0);
    }

    @Override
    public void onAttachedToRecyclerView(RecyclerView recyclerView) {
        super.onAttachedToRecyclerView(recyclerView);
    }

    @Override
    public void onBindViewHolder(final RecyclerView.ViewHolder holder, int position) {
        switch (holder.getItemViewType()) {
            case TYPE_TEXT_VIEW:
                String data = dataList.get(position - 1);
                SimpleTextViewHolder textHolder = (SimpleTextViewHolder)holder;
                textHolder.tv.setText(data);
                break;

            //6. Handle the RewardView type and call the saveMoment to fetch the reward.
            case TYPE_REWARD_VIEW:
                final KiipNativeRewardViewHolder rewardHolder = (KiipNativeRewardViewHolder)holder;
                if (!rewardHolder.isRewardLoaded()) {
                    Kiip.getInstance().saveMoment("<MOMENT_ID>", new Kiip.Callback() {
                        @Override
                        public void onFailed(Kiip kiip, Exception exception) {
                           //Handle exception
                           Log.e(TAG, exception.toString()); 
                        }
                        @Override
                        public void onFinished(Kiip kiip, Poptart poptart) {
                            if (poptart != null) {
                                //Pass the KiipNativeRewardView instance of KiipNativeRewardViewHolder (rewardHolder)
                                poptart.showNativeReward(rewardHolder.nativeRewardView);
                            }
                        }
                    });
                }

                break;
        }
    }

    class SimpleTextViewHolder extends RecyclerView.ViewHolder {
        TextView tv;
        public SimpleTextViewHolder(View view){
            super(view);
            tv = (TextView) view.findViewById(R.id.title);
        }
    }
  }
}

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.