Using Word of Mouth with the Tapstream Android SDK

First, integrate the latest Android SDK.

Integration instructions for Android

Tapstream Word of Mouth gives you the ability to track and reward users for sharing your app with a friend.

Try creating a Word of Mouth campaign to get a feel for how Word of Mouth 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 Word of Mouth functionality is used.

About Word of Mouth

A Word of Mouth 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 Word of Mouth 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.

Tapstream tracks how many installs result from each link, and allows you to check if a user has earned a reward, defined by you, by referring their friends to your app.

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