Using App Invites with the Tapstream iOS SDK

First, integrate the latest iOS SDK.

Integration instructions for iOS

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 iOS SDK. Once you've done so, come back here and follow the instructions below.

If using CocoaPods, make sure that your Podfile includes a dependency on 'Tapstream/WordOfMouth' (The 'Tapstream' dependency will include this by default).

Otherwise:

• Copy the WordOfMouth folder from the SDK archive, and paste it into your project directory.
• Open your Xcode project.

• Drag the WordOfMouth folder from the your project directory and drop it into Xcode's Project Navigator. It should be placed as a child of the root project node.

• In your project settings, add a framework reference to Social.framework

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:

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 "TSTapstream.h"
#import "TSWordOfMouthController.h"

// ...

TSWordOfMouthController *wom = (TSWordOfMouthController*) [TSTapstream wordOfMouthController];

[wom getOfferForInsertionPoint:@"launch" completion:^(TSOfferApiResponse* r){
    if(r != nil && ![r failed]){
        [wom showOffer:r.offer parentViewController:self];
    }
}];

Notes:

• The -offerForInsertionPoint:result: 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:parentViewController: method adds a subview to the current view, and needs a pointer to the current UIViewController in order to do so. In this example, the containing object inherits from UIViewController and so self is passed as the parent view controller.

If your use case allows, it is safe to pre-load the offer for later display, as in this example:

@interface MyViewController
@property(nonatomic, strong) TSOffer* offer;
@property(nonatomic, strong) TSWordOfMouthController* wom;
@end

@implementation MyViewController
- (void)viewDidLoad
{
    [super viewDidLoad];

    self.wom = [TSTapstream wordOfMouthController];
    [self.wom getOfferForInsertionPoint:insertionPoint completion:^(TSOfferApiResponse* r){
        if(r != nil && ![r failed]){
            self.offer = r.offer;
        }
    }];
}

- (IBAction)showWomInterstitial
{
    if(self.offer != nil){
        [self.wom showOffer:self.offer, parentViewController:self];
    }
}
@end

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 "TSTapstream.h"
#import "TSWordOfMouth.h"

// ...

TSWordOfMouthController *wom = [TSTapstream wordOfMouthController];
[wom getRewardList:^(TSRewardApiResponse* r) {
    [results enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
        TSReward *reward = (TSReward *)obj;
        // Rewards present in response.rewards are those that are due for
        // delivery. After a reward is delivered, consume it so that it won't
        // be delivered twice.

        if(deliverySuccess) {
            [wom consumeReward:reward];
        }
    }];

}];