Trace

Trace is a testing and inspection tool for your Tealium EventStream and Tealium AudienceStream configuration. Use a trace to capture a visitor workflow and watch how events and customer data is processed in real-time.

Mobile Trace Tool

Supported platforms

The following platforms support the Mobile Trace Tool:

• Android (Kotlin)
• iOS (Swift v2.x)

Do not add a trace to bulk events.
Do not add a trace as a permanent parameter to monitor production data.

How it works

The Mobile Trace Tool enhances the trace feature by providing a QR code that is scannable by your device, enabling you to quickly view events coming from the Tealium Mobile SDKs.

After clicking Start Trace in the tool, once per Tealium platform session, a QR code is automatically injected into the main browser window each time you start a new trace.

QR codes are generated for each platform (Android or iOS). After you scan the appropriate QR code with your mobile device’s camera, click the link from the QR code to start the app and pass trace parameters to the Tealium SDK. The Tealium SDK receives the trace ID (along with other parameters) and inserts the trace ID into the data layer for the current session.

All subsequent events are recorded in the trace session until you end the session or leave the trace.

The following diagram illustrates how it works:

Install

To use this tool:

1. Install the Tealium Tools browser extension for your browser.
2. After installation has completed, open the Tealium Tools extension.
3. Click the Tool Catalogue tab.
4. Click Mobile Trace Tool.

URL schemes

To use the Mobile Trace Tool, determine which URLs are handled by your mobile apps to configure the URL schemes.

The QR code trace feature launches your app from a URL and listens for a specific query parameter. To launch your app directly from a URL, your app must have registered itself to handle specific domains.

Typically, most apps already handle specific URLs. For example, if your website domain is https://mycompany.com, your app registers itself as a handler for this domain and, if your app is installed on a user’s device, the user is prompted to launch the link in your app instead of within a browser.

Some apps register custom URL schemes such as mycompanyapp:// instead of http or https. These also work with the Mobile Trace Tool.

Once you have established which URL schemes launch your app, enter these into the input fields in the Mobile Trace Tool. The tool supports different schemes for Android and iOS if necessary, but are usually the same for both platforms.

Click Save next to each URL scheme to store the setting in the browser’s localStorage. Click the blue pencil icon to edit the URL schemes as needed.

Start a trace

Before starting a trace, verify that you are in the Tealium server-side platform. Click Start Trace in the Mobile Trace Tool to start a new trace and add the Mobile Trace QR codes into the trace window.

After starting a trace, close the Tealium Tools UI as it’s not required for the rest of your session.

Subsequent traces are started directly from Tealium and the QR code automatically refreshes each time a new trace starts. Scan the QR code with your device’s camera, and click the link to launch your app and automatically begin tracing. Any Tealium events generated by your app after joining the trace are recorded in your trace session.

Leave trace

If you leave a trace session without ending it, you are able to rejoin the same trace from a different device without losing the history of that trace session.

To leave a trace:

1. Select the Leave Trace checkbox in the trace UI.
2. Scan the QR code again with your device’s camera.
3. Click the link for your device to no longer participate in the trace session.

End of Visit (AudienceStream)

Testing “End of Visit” actions in Tealium AudienceStream requires a signal to immediately end the visitor’s session, otherwise it is necessary to wait for the session to expire normally.

In the Mobile Trace Tool, end the session immediately by selecting the End Visitor Session checkbox, which adds a parameter to the QR code that makes the SDK send a kill_visitor_session event.

Charles Proxy

Use the Charles Web Debugging Proxy to start a trace from an application using the Mobile SDK and the Tealium Collect tag.

Requirements

• Charles Proxy
• Tealium server-side account

Setup

To set up your mobile device to proxy traffic through Charles on your computer, follow the instructions for Android or iOS device.

Using a rewrite

Run your application using Charles as the proxy and filter the network traffic for teal. Right-click the request and select Copy URL.

From the Charles menu, select Tools > Rewrite to open the Rewrite Settings dialog.

To add a location:

1. Select the Enable Rewrite checkbox and click Add below the Location list.

2. Enter Add Trace ID in the Name field and click Add to add a location.

3. Enter the necessary information in the location fields and enter the Collect tag URL in Host.

   If you click outside of the Edit Location dialog box, Charles automatically determines the additional URL components.

4. Leave the Query field empty and click OK.

To add an action:

1. Click Add below the Action list and set Type to Body from the list.
2. In the Where section, select the Request checkbox.
3. In the Match section, set Value to "data":{ and select the Match whole value checkbox.
4. In the Replace section, set Value to "data":{"cp.trace_id":"TRACE_ID", and select the Replace first checkbox.
5. Click OK and Apply changes.

After completing the steps, browse your application and view the requests in the AudienceStream or EventStream trace session. To run another trace, launch Charles and edit the existing rewrite rule to change the TRACE_ID placeholder to your new trace ID value.

Manual

If you are in development mode using an emulator, or do not want to use Charles, you can add and leave a trace manually with native code.

Start a trace (Manual)

To start and run a trace manually, add the trace ID to the volatile data within your native code.

instance.getDataSources().getVolatileDataSources().put("tealium_trace_id", "TRACE_ID");

tealium?.volatileData()?.add(data: ["tealium_trace_id": "TRACE_ID"])

NSDictionary *tealiumTrace = @{@"tealium_trace_id":@"TRACE_ID"};
[[Tealium instanceForKey:TEALIUM_INSTANCE_ID] addVolatileDataSources: tealiumTrace];

End a trace (Manual)

To end a trace manually and simulate any “End of Visit” enrichments, add the following track to the optional data anywhere within the app:

Map<String, Object> data = new HashMap<>(1);
data.put("event", "kill_visitor_session");
data.put("cp.trace_id", "TRACE_ID");

tealium?.trackViewWithTitle("SCREEN_NAME", dataSources: ["event":"kill_visitor_session", "cp.trace_id":"XXXXX"])