Native Integration via API

Talkable provides an API that can be utilized to implement a fully native referral program interface if you don’t want to use included WKWebView-based functionality. Below are the methods necessary to integrate the Talkable referral loop into your iOS app.

1. Create an Origin

The Origin is a user event (e.g. a purchase or simply opening the app) that initiates the referral chain. Create an Origin to retrieve an Offer and display it to an Advocate.

To create an Origin, make a request to Origins endpoint using the createOrigin:withHandler: method. If the request is successful, the handler block will receive attributes of created Origin and Offer entities.

NSDictionary* originParams = @{
    TKBLOriginTypeKey: TKBLOriginTypePurchase,
    TKBLOriginDataKey: @{
        TKBLPurchaseEmailKey: @"test@example.com",
        TKBLPurchaseSubtotalKey: @"17.43",
        TKBLPurchaseOrderNumberKey: @"100125",
        @"campaign_tags": @"your-campaign-tag"
    }
};

[[Talkable manager] createOrigin:originParams withHandler:^(NSDictionary* response, NSError* error) {
    NSDictionary* offerParams = [response objectForKey:TKBLOfferKey];
}];

2. Create a Share

Sharing an Offer is the next step in the referral chain. You will need the short_url_code of the Offer obtained from a previous request.

NSString* shortUrlCode = [offerParams objectForKey:TKBLOfferShortUrlCodeKey];

Social Share

The Talkable SDK provides several ways to share an Offer using social media channels.

  1. socialShare: method will display a sharing dialog directly. Supported channels are Facebook and Twitter.

    SLComposeViewController* sheet = [[Talkable manager] socialShare:@{
      TKBLShareChannel:TKBLShareChannelTwitter,
      TKBLOfferClaimUrlKey:[claimLinks objectForKey:TKBLShareChannelTwitter],
      TKBLShareMessage:@"Personalized message",
      TKBLShareImage:@"Image URL as NSString", // You can also pass a UIImage
      TKBLOfferShortUrlCodeKey:shortUrlCode
    }];
    
    [self presentViewController:sheet animated:YES completion:^{}];
    
  2. nativeShare: method will display a native iOS sharing dialog.

    NSDictionary* claimLinks = [offerParams objectForKey:@"claim_links"];
    
    UIActivityViewController* sheet = [[Talkable manager] nativeShare:@{
        TKBLOfferShortUrlCodeKey: shortUrlCode,
        TKBLOfferClaimUrlKey: [claimLinks objectForKey:TKBLShareChannelOther]
    }];
    
    [self presentViewController:sheet animated:YES completion:^{}];
    

3. Implement your own way for the Advocate to share the link. Upon a successful share, call the createSocialShare:channel:withHandler: method to sync the share with Talkable and create a Share record.

[[Talkable manager] createSocialShare:shortUrlCode channel:TKBLShareChannelOther withHandler:^(NSDictionary* response, NSError* error) {
    NSDictionary* rewardParams = [response objectForKey:@"reward"];
}];

Note

This method will be called automatically when you use socialShare: or nativeShare: methods.

Email Share

To share an Offer via email, simply use the createEmailShare:recipients:withParams:andHandler: method to send an API request. Talkable will send the emails for you. You will need to provide an interface for the user to specify recipients’ email addresses, a subject, and a personal message.

NSString* recipients = @"customer@example.com,elon@musk.com"; // comma separated email addresses
NSDictionary* emailShareParams = @{
    @"subject": @"Custom Email Subject",
    @"body": @"Personal message that will be added to the email body",
    @"reminder": @NO // Whether Talkable should send a reminder email later
};

[[Talkable manager] createEmailShare:shortUrlCode recipients:recipients withParams:emailShareParams andHandler:^(NSDictionary* response, NSError* error) {
    // process delivery stats
}];

3. Check for Reward

If a Talkable campaign is configured to give a reward to the Advocate just for sharing, the API call to create a Share will return a Reward you can display immediately. In most cases, however, the Advocate will receive a reward after a Friend responds to a shared link, e.g. makes a purchase. To check whether the current user has any outstanding rewards, use the retrieveRewardsWithHandler: method.

[[Talkable manager] retrieveRewardsWithHandler:^(NSDictionary* response, NSError* error) {
    NSArray *rewards = (NSArray *)[response objectForKey:@"rewards"];
}];

Extra Functionality

Retrieve an Offer by Short Code

If you need to access an Offer for the Origin you’ve created earlier, store the offer’s short_url_code and then use retrieveOffer:withHandler: method to fetch the Offer.

[[Talkable manager] retrieveOffer:shortUrlCode withHandler:^(NSDictionary* response, NSError* error) {
    NSDictionary* offerParams = [response objectForKey:TKBLOfferKey];
}];

Alternatively, you can subscribe to a TKBLDidReceiveReward notification as described in the Advanced Usage section.