Swift: Tracking Quick Start Guide

Swift: Tracking Quick Start Guide

by on ‎12-22-2017 06:35 AM - edited 2 weeks ago (881 Views)

Basic Concepts

This document covers all the basics to get you up and running with Tealium as quickly as possible. In most cases, the API calls described here are all you will ever need to implement, unless you want to use some of the more advanced features of the library, which are covered in separate documents (see Modules Documentation).

Tracking Calls

The Tealium tracking API provided by the Swift library is designed to capture two types of events:

  • Screen Views
    • In general, we advise that every screen in your app is tracked (usually in viewDidAppear or similar), and any other relevant variables should be passed in a Dictionary in the data parameter.
  • User Interation Events (e.g. Button Clicks)
    • You should add track calls for significant events in your app, e.g. a call-to-action button, "Buy Now", "Add To Cart".

Adding more tracking calls upfront, before the app is deployed to the App Store, will reduce the need to add more tracking at a future date, and reduce the need for app updates. If in doubt, track it; tracking calls can be filtered out/ignored if not needed later on, but they are more tricky to add to your app later.

Helper Class

We recommend the use of a helper class to abstract the Tealium API implementation from the rest of your app. This will give you a single entry point from which to call Tealium, and in the event that we make breaking changes in future releases (we always try not to!), you only need to update the code in your helper file, and not in every single ViewController or Swift file. A sample helper class is provided in the GitHub repo.

Sample Code

Initialization/Instantiation

This code should generally be run as part of your helper class to initialize Tealium for the first time.

	// REQUIRED Config object for lib
	let config = TealiumConfig(account: "tealiummobile",
	                           profile: "demo",
	                           environment: "dev",
	                           datasource: "test12",
	                           optionalData: nil)
      // OPTIONALLY set log level
      config.setLogLevel(logLevel: .verbose)
      
        // REQUIRED Initialization - recommend making tealium reference a member of your singleton helper; it should only be instantiated once
        let tealium = Tealium(config: config) {
                        
                    // Optional processing post init.
                            
        }

Modules

The Tealium Swift library is modular. This means you only need to install the specific components you need, and any you don't need are excluded from your build. This saves resources while your app is running, and makes sure your end users get the best possible experience. See https://community.tealiumiq.com/t5/Tealium-for-Swift/x/ta-p/20533 for recommended module lists.

Track Screen Views

This code block will track a screen view on the homescreen, passing a Dictionary containing two key-value pairs, the first representing the customer id, and the second, an array of product IDs purchased in this transaction (in this instance, containing 1 product only). You may optionally specify a completion block, but you may pass nil if you don't need special completion handling.

// assuming 'tealium' has already been instantiated
tealium?.trackView(title: "Buy Now", data: ["customer_id" : "1234567890-a", "product_ids" : ["widget123"]], completion: nil)

Track User Events

This code block will track a button click on "Buy Now", passing a Dictionary containing a single key-value pair, representing the customer id. You may optionally specify a completion block, but you may pass nil if you don't need special completion handling.

// assuming 'tealium' has already been instantiated
tealium?.track(title: "Homescreen", data: ["customer_id" : "1234567890-a"], completion: nil)

Add Persistent Data

Persistent data storage should be used for those variables which rarely change during the app's lifecycle, but are required to be sent on every tracking call. An example of this may be a customer ID that stays the same until the user logs out. Persistent data remains set across multiple app launches (since it is stored on disk), and can only be modified by deleting the data through the persistent data API, or overwriting an existing key with a new value. Persistent data is merged with any dictionary passed in each tracking call (trackView or track), and sent to any enabled dispatch services. NOTE: Persistent Data storage is backed by either UserDefaults or File Storage, depending on the modules currently enabled.

tealium?.persistentData()?.add(data: ["customer_id":"1234567890-a"])

Add Volatile Data

Volatile data storage should be used for those variables that do not change during a single launch of the app, but may change for future launches. An example of this may be some sort of session ID, which is regenerated each time the user relaunches the app. Volatile data works in a similar way to persistent data, except that it is only kept in main memory, and never written to disk. Thus, force closing an app will clear all volatile data previously set. From the point it is set, volatile data will be sent on each subsequent tracking call, and its data merged with any Dictionary passed in to the tracking call.

tealium?.volatileData()?.add(data: ["session_id":"1234567890232"])