Tapstream

Setting up campaigns

Running reports

APIs

Advanced

Tapstream SDKs

Integrating the Tapstream Mac 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 'TapstreamMac'

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 Mac SDK.

Get the latest Mac 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.

Including the AdSupport framework

Warning: This requires explicit user consent.

If you collect Allow Ad Tracking consent from your users, you can optionally collect the Identifier for Advertisers (IDFA) from your app installation:

First, add the AdSupport framework:

  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".

  4. In your project settings add a framework reference to IOKit.framework

Importing and initializing the SDK

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

#import "TSTapstream.h"

Then, in the -applicationDidFinishLaunching: 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];

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];

Collecting hardware identifiers

Tapstream collects the WiFi MAC address of Mac OS X devices automatically. You can also collect the Mac OS X device serial number and provide it to Tapstream manually, by modifying your Tapstream configuration accordingly:

TSConfig* config = [TSConfig configWithAccountName:@"YOUR_TAPSTREAM_ACCOUNT_NAME" sdkSecret:@"YOUR_SDK_SECRET"];
config.serialNumber = @"<Serial number value goes here>";
[TSTapstream createWithConfig:config];

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"];

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

You can suppress the automatic collection of the WiFi MAC address by adding the following line to your Tapstream config:

// This hardware identifier will be automatically collected and sent
// unless you opt-out by setting it to NO, as shown here.
config.collectWifiMac = NO;

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>";

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;