Tapstream

Setting up campaigns

Running reports

APIs

Advanced

Tapstream SDKs

Using App Invites with the Tapstream Android SDK

First, integrate the latest Android SDK.

Integration instructions for Android

Tapstream App Invites give you the ability to reward users for sharing your app with a friend.

Try creating a Word of Mouth campaign to get a feel for how App Invites offers are designed and presented.

First, implement the latest Tapstream Android SDK. Once you've done so, come back here and follow the instructions below.

The following examples assume that the Tapstream SDK has been initialized in the usual manner before any App Invites functionality is used.

About App Invites

An App Invites offer is a customizable modal that asks your user to share the app with another user in exchange for a reward, like this:

The configurable App Invites offer modal

When the user clicks the call to action, Tapstream shows a share card that allows the user to share a unique link via iMessage/SMS, email, Facebook, or Twitter.

All details of each offer are controlled from within the Tapstream dashboard - you don't need to define its style, images, messaging, or reward during integration.

Showing offers

Your app probably has several locations at which you might want to show an offer. These locations are called "insertion points". Each insertion point should be uniquely identified with a string name that you entered in your Tapstream dashboard. At each insertion point in your code, you'll need to ask the SDK for eligible offers.

Here's how to query and display an offer at an insertion point called "launch":

import com.tapstream.sdk.ApiFuture;
import com.tapstream.sdk.Callback;
import com.tapstream.sdk.Tapstream;
import com.tapstream.sdk.wordofmouth.Offer;
import com.tapstream.sdk.wordofmouth.OfferApiResponse;
import com.tapstream.sdk.wordofmouth.WordOfMouth;

public class MyMainActivity extends Activity {
    // ...

    @Override
    protected void showOffer(String insertionPoint) {
        // You probably have a uiHandler in your activity already.
        final Handler uiHandler = new Handler(Looper.getMainLooper());
        final Activity mainActivity = this;

        String insertionPoint = "launch";
        ApiFuture<OfferApiResponse> resp = Tapstream.getInstance().getWordOfMouthOffer(insertionPoint);

        // Offers may take time to fetch; you are encouraged not to block your main thread on this retrieval.
        resp.setCallback(new Callback<OfferApiResponse>() {
            @Override
            public void success(OfferApiResponse result) {
                final Offer o = result.getOffer();

                // Bounce back to UI thread to show WOM offer.
                uiHandler.post(new Runnable() {
                    @Override
                    public void run() {
                        statusView.setText("Success. Displaying offer.");
                        WordOfMouth wom = Tapstream.getInstance().getWordOfMouth();
                        View parent = findViewById(R.id.main_layout);
                        wom.showOffer(mainActivity, parent, o);
                    }
                });
            }

            @Override
            public void error(Throwable reason) {
                // Handle a failure to retrieve an offer
            }
        });

        // You may also simply resp.get() to block the current thread.
    }
}

Notes:

  • The getWordOfMouthOffer method will not always return an offer. The rules that decide whether an offer is eligible to be shown at a particular insertion point, at a particular time, are managed in your Tapstream dashboard.

  • The showOffer method should be called with your main activity and main layout view. In the above example, this refers to the main activity.

Checking for rewards

When one of your users accepts an offer and successfully refers friends to your app, they may become eligible to receive a reward. Rewards are defined in your Tapstream dashboard.

At least once per session (but ideally, periodically over the course of a user session), your code should check for available rewards. If there are available rewards, your code should deliver the reward to the user and then tell the SDK that the reward has been consumed so that it will not be delivered again.

Here's how you might check for and consume available rewards:

import com.tapstream.sdk.ApiFuture;
import com.tapstream.sdk.Callback;
import com.tapstream.sdk.Tapstream;
import com.tapstream.sdk.wordofmouth.Reward;
import com.tapstream.sdk.wordofmouth.RewardApiResponse;
import com.tapstream.sdk.wordofmouth.WordOfMouth;

// ...

ApiFuture<RewardApiResponse> resp = Tapstream.getInstance().getWordOfMouthRewardList();

// Again, try not to block on retrieving this future.
resp.setCallback(new Callback<RewardApiResponse>() {
    @Override
    public void success(RewardApiResponse result) {
        WordOfMouth wom = Tapstream.getInstance().getWordOfMouth();
        for(Reward reward: result.getRewards()){
            // Check reward.getRewardSku() and deliver that reward to your user.
            // If the reward was successfully delivered, then consume it so it
            // will not show up when we query rewards in the future:
            while(!wom.isConsumed(reward)){
                deliverReward(reward.getRewardSku());
                wom.consumeReward(reward);
            }
        }
    }

    @Override
    public void error(Throwable reason) {
        // Handle a failure to retrieve an offer
    }
});
// ...