Integrating the Tapstream iOS SDK

You can install Tapstream via Cocoapods or via source bundle.

Installing the SDK using CocoaPods

If project is not already using Cocoapods, you can follow the instructions on cocoapods.org to get up and running.

After that, you can simply add Tapstream as a dependency in your Podfile:

pod 'TapstreamIOS/Core' # For all projects
pod 'TapstreamIOS/WordOfMouth' # For projects requiring the Word of Mouth feature
pod 'TapstreamIOS/InAppLanders' # For projects requiring the In-App Landers feature

# or

pod 'TapstreamIOS' # Install all of the above (for projects that want all features)

Then, run pod install in your project directory, and the SDK should appear under Pods in XCode (remember to open the .xcworkspace file).

Installing the SDK using the source bundle

First, get the latest iOS SDK.

Get the latest iOS SDK

Then:

  • Extract the SDK zip file.
  • Copy the Tapstream folder and paste it into your project directory.
  • Open your Xcode project.
  • Drag the Tapstream folder from the Finder window and drop it into Xcode's Project Navigator. It should be placed as a child of the root project node.

The WordOfMouth folder contains source files and assets only applicable to developers using the Word of Mouth marketing feature. See the Word of Mouth section for integration instructions. Likewise, the in-app-landers folder need not be included in projects not using this feature -- see the In App Landers documentation for more details.

You don't need to include these folders in your project if you are not going to integrate these features. Mac-only projects may additionally omit the ios-only folder.

Including the AdSupport framework

For optimal functionality, your application should include the AdSupport framework.

To include the AdSupport framework in Xcode, do the following:

  1. Select your Project in the Project Navigator
  2. Scroll down to "Linked Frameworks and Libraries" (on the "General" tab), and click the +
  3. Select AdSupport.framework and click "Add".

Importing and initializing the SDK

In your project's AppDelegate.m file, import the Tapstream SDK:

#import "TSTapstream.h"

Then, in the -application:didFinishLaunchingWithOptions: method of the AppDelegate, create the TSTapstream singleton with your Tapstream account name and SDK secret:

TSConfig* config = [TSConfig configWithAccountName:@"YOUR_TAPSTREAM_ACCOUNT_NAME"
                                         sdkSecret:@"YOUR_SDK_SECRET"];
[TSTapstream createWithConfig:config];

Collecting hardware identifiers

If your application includes the AdSupport framework, Tapstream will automatically collect the Identifier for Advertisers (referred to as the IDFA, IFA, or 'Advertiser Identifier'). Tapstream uses this identifier for attribution, in accordance with Apple's policy on its collection.

When submitting your app to Apple, declare your use of the IDFA and state that your app uses the Advertising Identifier to "Attribute this app installation to a previously served advertisement".

If you wish to suppress the automatic collection of the IDFA, you can do so by modifying your Tapstream configuration.

To support legacy iOS devices, Tapstream also collects WiFi MAC addresses from iOS devices automatically, when available.

Firing SDK events

The SDK will fire two types of events automatically:

  • An install event, the first time the app runs
  • An open event, every time the app runs.

The install event is called [platform]-[appname]-install, and the open event is called [platform]-[appname]-open, where [platform] is the device's platform (iOS, Android, etc.) and [appname] is your app's shortname.

Additional SDK events

You may fire additional events from anywhere in your code. This is useful for tracking engagement events, user progress, and other LTV metrics.

Firing an event is simple and can be done like this:

TSEvent *e = [TSEvent eventWithName:@"created-account" oneTimeOnly:NO];
[[TSTapstream instance] fireEvent:e];

This example fires an event called created-account, but you may call your events anything you like. Event names are case insensitive.

The Tapstream SDK is threadsafe, so you may fire events from any thread you wish.

Firing events with custom parameters

Tapstream also allows you to attach key/value pairs to your events. The keys and values must be no more than 255 characters each (once in string form).

Custom event parameters and values are available via the Tapstream postback system, the Reporting tab of the Tapstream dashboard, and the Tapstream API suites.

In the following example, an event called level-complete with custom parameters for score and skill is fired.

TSTapstream *tracker = [TSTapstream instance];

TSEvent *e = [TSEvent eventWithName:@"level-complete" oneTimeOnly:NO];
[e addValue:@"15000" forKey:@"score"];
[e addValue:@"easy" forKey:@"skill"];
[tracker fireEvent:e];

Global custom event parameters

You may find that you have some data that needs to be attached to every single event sent by the Tapstream SDK. Instead of writing the code to attach this data in each place that you send an event, add these data values to the global event parameters member of the config object. The parameters in this dictionary will automatically be attached to every event, including the automatic events fired by the SDK.

For example:

TSConfig* config = [TSConfig configWithAccountName:@"YOUR_TAPSTREAM_ACCOUNT_NAME"
                                         sdkSecret:@"YOUR_SDK_SECRET"];
[config.globalEventParams setValue:@"92429d82a41e" forKey:@"user_id"];

Automatic IAP tracking

In-app purchases are automatically tracked by the Tapstream SDK. This is the default (and recommended) behavior.

In order to provide accurate tracking of your IAP revenue, receipts will automatically be collected and validated on the Tapstream server. However, you should still validate your receipts independently of Tapstream and only provide IAP goods to users who have made valid purchases.

To make the Tapstream server-side receipt validation as accurate as possible, you should provide your bundle ID and short version string as hardcoded values when you initialize the SDK:

TSConfig* config = [TSConfig configWithAccountName:@"YOUR_TAPSTREAM_ACCOUNT_NAME"
                                         sdkSecret:@"YOUR_SDK_SECRET"];
config.hardcodedBundleId = @"com.mycompany.MyApp";  // String matching your CFBundleIdentifier value
config.hardcodedBundleShortVersionString = @"1.0";  // String matching your CFBundleShortVersionString value

Note that these values should be string literals - do not dynamically fetch these values from your bundle. This is a safety precaution to help guard against receipt tampering. Remember to keep these values up to date when you release new versions of your app.

Tracking other types of purchase events

If your app allows users to make purchases that are not processed by the standard StoreKit in-app purchase system, you may want to fire completely custom purchase events. For example:

TSTapstream *tracker = [TSTapstream instance];
TSEvent *e = [TSEvent eventWithTransactionId:@"3da541559918a"
    productId:@"com.myapp.coinpack100"
    quantity:1
    priceInCents:299
    currency:@"USD"];
[tracker fireEvent:e];

If you don't know or cannot provide the price and currency of the transaction in your app, you can omit these details. The value of the purchase event will then be determined by the value that you set in your Tapstream dashboard.

For example:

TSTapstream *tracker = [TSTapstream instance];
TSEvent *e = [TSEvent eventWithTransactionId:@"3da541559918a"
    productId:@"com.myapp.coinpack100"
    quantity:1];
[tracker fireEvent:e];

Verifying your SDK integration

Once you've completed the integration, you can log in to your Tapstream dashboard and verify that your integration is delivering events to Tapstream. Run your app and visit the Events section of the dashboard. You should now see at least one event, like platform-myapp-install.

The SDK status light in the header of the dashboard will now be green to indicate that Tapstream has received an event from your integration.

Controlling logging

The log output of Tapstream can be redirected (or quelled) by providing a handler to receive the messages.

Make sure to define the logging behavior before you initialize the SDK.

Here's how you might redirect Tapstream messages to a custom logging system:

#import "TSLogging.h"

// ...

[TSLogging setLogger:^(int logLevel, NSString *message) {
    MyCustomLoggingSystem(message);
}];

Changing hardware ID collection

If you prefer that Tapstream not collect the IDFA or WiFi MAC, you can opt-out by adding the following to your Tapstream configuration. (Note that this is not recommended.)

// These hardware identifiers will be automatically collected and sent
// unless you opt-out by setting them to false, as shown below. This is NOT recommended.
config.autoCollectIdfa = NO; // Disable IDFA collection
config.collectWifiMac = NO; // Disable WiFi MAC collection

If you need to collect deprecated hardware IDs, you can add them to your config as shown here:

// These hardware identifiers are optional and are not collected automatically.
// If you wish to send them, you must opt-in by providing values, as shown here:
config.odin1 = @"<ODIN-1 value goes here>";
config.openUdid = @"<OpenUDID value goes here>";
config.secureUdid = @"<SecureUDID value goes here>";

Changing the default events

Automatic install and open events can be renamed, and automatic install, open, and iOS purchase events may suppressed entirely by modifying the config object that you used to instantiate the SDK. For example, if you wanted to rename the install and open events, you would set the config object like this:

config.installEventName = @"my-install-event";
config.openEventName = @"my-open-event";

If you wanted to suppress the automatic install, open, and iOS purchase events, you would set the config object like this:

config.fireAutomaticInstallEvent = NO;
config.fireAutomaticOpenEvent = NO;
config.fireAutomaticIAPEvents = false;