Using Word of Mouth with the Tapstream PhoneGap SDK

First, integrate the latest PhoneGap plugin.

Integration instructions for PhoneGap

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.

You can use Word of Mouth on PhoneGap by integrating two APIs. Before calling these APIs, ensure that the app session has initialized its Tapstream integration.

Both of these APIs are keyed on the Tapstream SDK-side session identifier and your Tapstream SDK secret. The SDK-side session identifier can be retrieved from the Tapstream config object. The Tapstream SDK secret is the secret you used to initialize the SDK, and can be found in your Account page.

Checking for offers

Use the Word of Mouth Offers API to retrieve a list of offers for which a given app session is eligible.

Checking for rewards

Use the Word of Mouth Rewards API to retrieve a list of rewards a given app session has earned.

Putting it together

With these two endpoints, you should have everything you need to get your Phonegap app integrated with Tapstream's Word of Mouth API. But, just in case, here are some details that might help a bit.

Displaying the offer

The offer endpoint includes some HTML to be rendered as the offer popup window. Within that HTML, you'll need to modify the "accept" and "close" links to perform the correct actions:

$(offerPopupHtml).find("a[href='accept']").click(function(e){
    e.preventDefault();
    // ... show sharing dialog
}

Preparing the share dialog

For the sharing dialog, you'll need to render the share link, replacing SDK_SESSION_ID with the user's Tapstream session id. To retrieve this value, you'll need to use the native SDK for each platform, since the session ID is stored in platform-specific preferences storage. Here's how to retrieve that session ID:

Java/Android

SharedPreferences prefs = context.getApplicationContext().getSharedPreferences("TapstreamSDKUUID", 0);
String uuid = prefs.getString("uuid", null);

Objective-C/iOS

NSString *uuid = [[NSUserDefaults standardUserDefaults] objectForKey:@"__tapstream_uuid"];

Once the session id is acquired, you'll be able to provide the full share text:

shareText = offer.message.replace("OFFER_URL", offer.offer_url.replace("SDK_SESSION_ID", sessionId));

Showing a sharing dialog

You're welcome to construct whatever dialog you like to share the offer, but we recommend using the platform-provided native sharing capabilities. To show a native sharing dialog, you'll need to interact with the underlying platform.

Java/Android

private void showShareDialog(String shareText){

    final Intent shareIntent = new Intent(Intent.ACTION_SEND);

    shareIntent.setType("text/plain");
    shareIntent.putExtra(android.content.Intent.EXTRA_TEXT, shareText);
    shareIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
    this.cordova.getActivity().startActivity(Intent.createChooser(shareIntent, "Share"));
}

Objective-C/iOS

- (void)showShareDialog:(NSString *)shareText
{
    UIActivityViewController* c = [[UIActivityViewController alloc]
    initWithActivityItems:@[shareText] applicationActivities:nil];

    __weak typeof(c) weakC = c;

    [c setCompletionHandler:^(NSString* activityType, BOOL completed){
        __strong typeof(weakC) strongC = weakC;

        if (completed) {
            // Do whatever on completed share
        }

        strongC.completionHandler = nil;

    }];
    // parent is some view controller
    [parent presentViewController:c animated:YES completion:nil];
}

Redeeming rewards

To provide the user with their reward, you'll need to check the rewards endpoint every so often to see if there's anything new. The rewards endpoint will always return the all-time rewards earned -- it has no concept of redemption. So, you'll want to keep track of which rewards have already been redeemed by the user.

A good place to keep this information for Phonegap is in localStorage. Leaving out the details of get_rewards_earned_list except to say that it returns a promise of some sort, here's how you might do that:

get_rewards_earned_list().then(function(rewardList){
    for(reward in rewards){
        key = "redeemed:" + reward.offer_id.toString();
        if(!localStorage.getItem(key)){
            //... Make a big fanfare for the user and give them the thing
            localStorage.setItem(key, true);
        }
    }
});