Tapstream

Setting up campaigns

Running reports

APIs

Advanced

Tapstream SDKs

Objective-C Swift

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 App Invites feature
pod 'TapstreamIOS/InAppLanders' # For projects requiring the Campaign 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 App Invites marketing feature. See the App Invites section for integration instructions. Likewise, the in-app-landers folder need not be included in projects not using this feature -- see the Campaign 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.

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

Adding a Bridging Header to your project

For Swift projects, you'll need to create a "bridging header", if you haven't already, to work with Tapstream's Objective-C source files. See Apple's documentation on mixed-source projects for more details.

In your bridging file, insert the following:

// For Tapstream/Core features (i.e. all projects)
#import "TSTapstream.h"

// For Tapstream/WordOfMouth features
#import "TSWordOfMouth.h"

// For Tapstream/InAppLanders features
#import "TSInAppLanders.h

Importing and initializing the SDK

In your project's AppDelegate.swift file, in the application:didFinishLaunchingWithOptions method of the AppDelegate, create the TSTapstream singleton with your Tapstream account name and SDK secret:

let config = TSConfig(accountName: "YOUR_TAPSTREAM_ACCOUNT_NAME", sdkSecret: "YOUR_SDK_SECRET")
TSTapstream.create(with: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:

let config = TSConfig(accountName: "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:

let tracker = TSTapstream.instance()
let e = TSEvent(transactionId: "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:

let tracker = TSTapstream.instance()
let e = TSEvent(transactionId: "3da541559918a",
                productId: "com.myapp.coinpack100",
                quantity: 1)!
tracker.fireEvent(e)

Collecting hardware identifiers

If your application has permission from the user to track, includes the AdSupport framework, and has IDFA collection enabled Tapstream will collect the Identifier for Advertisers (referred to as the IDFA, IFA, or 'Advertiser Identifier').

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 would like to enable IDFA collection you can do so by modifying your Tapstream configuration.

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:

let e = TSEvent(name:"created-account", oneTimeOnly:false)!
TSTapstream.instance().fire(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.

let tracker = TSTapstream.instance()

let e = TSEvent(name:"level-complete", oneTimeOnly: false)!
e.addValue("15000", forKey:"score")
e.addValue("easy", forKey: "skill")
tracker.fire(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:

let config = TSConfig(accountName: "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:

TSLogging.setLogger { (logLevel, msg) in
    MyCustomLoggingSystem(message!)
}

Changing hardware ID collection

To enable IDFA collection make sure the AdSupport framework is present and add the following to your Tapstream configuration:

config.autoCollectIdfa = true

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 = false;
config.fireAutomaticOpenEvent = false;
config.fireAutomaticIAPEvents = false;