Installing Trackingplan

Trackingplan will monitor traffic between your app and data destinations and automatically warn you about any changes or issues in your analytics implementations like hit drops, missing properties, rogue events, and more.

☝🏻

The recommended way to install Trackingplan for iOS is to use Swift Package Manager, as it will simplify the process of installing and upgrading Trackingplan. To do this, follow the steps below.

In Xcode, add the Trackingplan dependency by navigating to File -> Swift Packages -> Add Package Dependency...

If you’re asked to choose a project, select the project you want to add Trackingplan to. If not, proceed to step 3.

When choosing a package repository, copy and paste https://github.com/trackingplan/trackingplan-ios into the search box and click Next.

Now, choose Version and leave the default selection for the latest version or customize if needed. To install previous versions of Trackingplan, you can manually complete this field with the appropriate version information.

Check the box next to Trackingplan and click Finish.

Verify that the Trackingplan library has been added to the Swift Package Dependencies section.

Then, in your application delegate’s - application(_:didFinishLaunchingWithOptions:) method, set up the SDK like so:

//
//  AppDelegate.swift
//  ...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.
        
        // Initialize Trackingplan SDK
        TrackingPlan.initialize(tpId: "#YourTrackingplanId")
        
        return true
}

Finally, import the SDK using the following command:

//
//  AppDelegate.swift
//  ...

import TrackingPlan

All set! You have successfully installed the Trackingplan iOS SDK. Please remember to validate Trackingplan is collecting data correctly by following these easy steps to ensure Trackingplan is automatically monitoring and documenting all the customer data you are using for your analytics, marketing, and sales.

If you have any other questions or problems during the process, don’t hesitate to contact support.

Installing iOS SDK with Cocoapods

☝🏻

Trackingplan also supports iOS installation using Cocoapods. To install Trackingplan with Cocoapods, complete the following steps.

First, add the Trackingplan dependency to your Podfile, like so:

pod 'Trackingplan', :git => 'https://github.com/trackingplan/trackingplan-ios.git'

In your application delegate’s - application(_:didFinishLaunchingWithOptions:) method, set up the SDK like so:

//
//  AppDelegate.swift
//  ...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.
        
        // Initialize Trackingplan SDK
        TrackingPlan.initialize(tpId: "#YourTrackingplanId")
        
        return true
}

Import the SDK with this command:

//
//  AppDelegate.swift
//  ...

import TrackingPlan

And that’s it! After completing these steps, remember to validate Trackingplan is collecting data correctly by following these easy steps.

If you have any other questions or problems during the process, don’t hesitate to contact support.

Installing iOS SDK in a Flutter project

TrackingPlan iOS platform dependency can be managed using Cocoapods (https://guides.cocoapods.org/using/getting-started.html#getting-started)

Your Flutter project is not using Cocoapods yet?

Move to the iOS folder inside your Flutter project folder. {project_name}/ios/
Initialise Cocoapods: $ pod init : this will create the Podfile.

Install:

Open the Podfile, uncomment, and set the platform and version at the top.

platform : ios, '13.0.0'

Add a line for the Trackingplan pod inside the target block:

pod 'Trackingplan', :git => 'https://github.com/trackingplan/trackingplan-ios.git'

Make sure that use_frameworks! is in place to disable dynamic frameworks

Sample Podfile (Project without Cocoapods):

platform :ios, '13.0.0'

...

target 'Runner' do
  use_frameworks!
    # Pods for Runner
  pod 'Trackingplan', :git => 'https://github.com/trackingplan/trackingplan-ios.git'
end

Move to the ios folder path {project_name}/ios/ and run the command $ pod install

Sample Podfile (Project already using Cocoapods):

target 'Runner' do
  use_frameworks!
  use_modular_headers!
  pod 'Trackingplan', :git => 'https://github.com/trackingplan/trackingplan-ios.git'
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

Setup:

Include Pods files in debug and release config:

Edit the file {project_name}/ios/Flutter/Debug.xcconfig and add at the end:

#include "Pods/Target Support Files/Pods-Runner/Pods-Runner.debug.xcconfig”

Edit the file {project_name}/ios/Flutter/Release.xcconfig and add at the end:

#include "Pods/Target Support Files/Pods-Runner/Pods-Runner.release.xcconfig" #include "Pods/Target Support Files/Pods-Runner/Pods-Runner.profile.xcconfig"

Update AppDelegate.swift in {project_name}/ios/Runner/

Import tracking plan at the top

Initialise tracking plan with the identifier provided inside the didFinishLaunchingWithOptions

Installing Trackingplan in Ionic for iOS platform

To support Trackingplan at an ionic app, you need to do some setup on each of the platforms. The process is straightforward and very similar to installing Trackingplan on mobile apps.

With that, all tracking requests made from any version of the app will be captured and monitored by Trackingplan.

💡

These instructions are for Capacitor Ionic apps, but please note that this will capture data for any analytics and marketing SDKs, no matter if they are Capacitor, Cordova, or js. For Cordova apps without Capacitor, installation is pretty similar.

Open the Podfile, uncomment, and set the platform and version at the top.
Add the following lines for the Trackingplan pod inside the target block:

use_frameworks!
use_modular_headers!
pod 'Trackingplan', :git => '<https://github.com/trackingplan/trackingplan-ios.git>'

Move to the ios/App folder and run:

pod install

Update AppDelegate.swift in ios/App/App to import Trackingplan at the top:

import Trackingplan

Initialize Trackingplan with the provided Trackingplan ID inside the didFinishLaunchingWithOptions function:

Trackingplan.initialize(tpId: "YourTrackingplanId")

Run the following commands:

ionic build
npx cap sync ios
npx cap run ios

Installing Trackingplan in Ionic for web apps

This step in necessary if you are using JS sdks for your analytics and marketing, instead of native (Cordova, Capacitor), or if you are using publishing your app as a website.

Include Trackingplan snippet on the app index.html.
You can get the snippet from your Trackingplan dashboard. You can find instructions here.

Set up Tags in iOS SDK

Tags are a pair of key-value strings that are used for tagging data sent to Trackingplan. These are completely customizable and can be extremely helpful to filter warnings affecting a specific app version, country, and so on, or perform root-cause analysis on them.

💡

Automating Tagging! For iOS and Android SDKs, the app_version tag will be automatically included without any additional configuration required. To include other tags such as country, build number, test name, or others, you can put them manually as indicated in the example below:

// Initialize Trackingplan SDK
Trackingplan.initialize(
		tpId: "YOUR_TP_ID".
		tags: [
			// "app_version": "1.0.0", Omitted, this is automatically set
			"lang": "en",
			"country": "us"
	]
)

Android SDK

Installing Trackingplan’s Android SDK using Android Studio

With Trackingplan for Android you can ensure your tracking is going as planned without changing your current analytics stack or code.

☝🏻

The recommended way to install Trackingplan for Android is to use Android Studio. For it, complete the following steps:

Note: Before starting the installation process, make sure your project targets API level 24 (Lollipop) or later.

First, add the Trackingplan dependency. To do this, expand the Gradle Scripts section.

Then, select the project-level build.gradle file and add com.trackingplan.client:adapter:1.8.0 as a classpath dependency to the dependencies section:

dependencies {   
    // ...
    classpath "com.trackingplan.client:adapter:1.8.0

" // ... }

After that, select the module-level build.gradle file and modify it as indicated below:

Add id 'com.trackingplan.client' to the plugins section.

plugins {
    // ...
    id 'com.trackingplan.client'
    // ...
}

Add implementation 'com.trackingplan.client:sdk:1.8.0' to the dependencies section.

dependencies {
    // ...
    implementation 'com.trackingplan.client:sdk:1.8.0'
    // ...
}

Next, in the onCreate method of your Application's Main Activity, set up the SDK like so:

Trackingplan.init("YOUR_TP_ID").start(this)

Then import the SDK with the following command:

import com.trackingplan.client.sdk.Trackingplan;

You have now successfully installed the Trackingplan Android SDK.

All set! After completing these steps, remember to validate Trackingplan is collecting data correctly by following these easy steps.

☝🏻

You can also install Trackingplan for Android by building it from the source code. For more information, visit our Github documentation.

Installing Android SDK in a Flutter project

To add Trackingplan to your Flutter app, first find the android directory inside your Flutter project and add the Trackingplan dependency like so:

Add com.trackingplan.client:adapter:1.8.0 as a classpath dependency to the dependencies section of the android/build.gradle file.

dependencies {   
    // ...
    classpath "com.trackingplan.client:adapter:1.8.0"
    // ...
}

Add implementation 'com.trackingplan.client:sdk:1.8.0' to the dependencies section of the android/app/build.gradle file.

dependencies {
    // ...
    implementation 'com.trackingplan.client:sdk:1.8.0'// ...
}

Apply com.trackingplan.client plugin in your android/app/build.gradle file.

apply plugin: 'com.android.application'
apply plugin: 'com.trackingplan.client' // <-- Trackingplan Plugin

Finally, find the MainActivity class (android/app/src/main/kotlin) and, in the onCreate method, set up the SDK like so:

Trackingplan.init("YOUR_TP_ID").start(this)

And of course, import the SDK:

import com.trackingplan.client.sdk.Trackingplan;

All set!

Installing Trackingplan in Ionic for Android platform

Add the Trackingplan classpath dependency to Android/build.gradle (the project-level build.gradle, not the one inside android/app but the one at the root of the android folder):

classpath "com.trackingplan.client:adapter:1.8.0"

Open the app/build.gradle file (the module-level Gradle file) at android/app/build.gradle.

In the dependencies block add:

implementation 'com.trackingplan.client:sdk:1.8.0'

At the top level add:

apply plugin: 'com.trackingplan.client'

Initialize the Trackingplan SDK in your MainActivity.java file located at android/app/src/main/java/MainActivity.java.

Add an onCreate method inside the MainActivity class and initialize Trackingplan with your Trackingplan Id:

import com.getcapacitor.BridgeActivity;
import android.os.Bundle;
import com.trackingplan.client.sdk.Trackingplan;

public class MainActivity extends BridgeActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Initialize Trackingplan with your TP ID
        Trackingplan.init("YourTrackingplanId").start(this);
    }
}

Set minSdkVersion = 24 or higher in android/variables.gradle.
Run the commands:

ionic build
npx cap sync android
npx cap run android

Advanced Options

Trackingplan for Android supports the following advanced options during its initialization:

Parameter	Description	Default
`enableDebug()`	Enables debug mode. Prints debug information in the console.	`disabled`
`environment(value)`	Allows to isolate the data between production and testing environments.	`PRODUCTION`
`dryRun()`	Enables dry run mode, which allows you test Trackingplan for Android without actually sending any data to Trackingplan.	`disabled`
`customDomains(map)`	Allows to extend the list of monitored domains. Any request made to these domains will also be forwarded to Trackingplan. The `map argument` must be a `key-value` with the domain to be looked for and the alias you want to use for that analytics domain.	`empty map`
`sourceAlias(value)`	Allows to differentiate between sources.	`android`
`tags(map)`	Allows to tag the data sent to Trackingplan. The `map argument` must be a `key-value` with the tag name and the tag value.	`empty map`
`getDataLayer`	Allows you to capture a real-data representation with browser-captured context, acting as a bridge between your website or applications and various analytics tools and facilitating the seamless transfer of essential data. If your data layer isn’t named `DataLayer` (e.g.: `customDataLayer`) be sure to specify the correct variable name accordingly.	`empty`

💡

Trackingplan.init("YOUR_TP_ID")
    .environment("development")
    .sourceAlias("Android app")
//  .tags(new HashMap<>(){{
//      put("tag1", "value1");
//  }})
//  .customDomains(new HashMap<>(){{
//      put("my.domain.com", "myanalytics");
//  }})
//  .enableDebug()
//  .dryRun()
    .start(this)

Trackingplan for Regression Testing

Trackingplan for Android supports running as part of your instrumented tests. This way, existing tests can be used to catch analytics data problems before they get into production. To do so, follow the steps below:

Add com.trackingplan.client:junit-tools:1.8.0 as a androidTestImplementation dependency to the dependencies section of your module-level build.gradle file:

dependencies {
    // ...
    androidTestImplementation "com.trackingplan.client:junit-tools:1.8.0"// ...
}

Import the TrackingplanJUnit:

import com.trackingplan.client.junit.TrackingplanJUnit;

In each JUnit file, add the imported rule to your instrumented test code:

@Rule
public TrackingplanRule trackingplanRule =
    TrackingplanJUnit.init("YOUR_TP_ID", "YOUR_ENVIRONMENT")
            .tags(new HashMap<>() {{
                put("test_title", "My test");
                put("test_session_name", "My session");
            }})
            //.dryRun()
            .newRule();

Or in Kotlin:

@get:Rule
val trackingplanRule = TrackingplanJUnit.init("YOUR_TP_ID", "YOUR_ENVIRONMENT")
    .tags(mapOf(
        "test_title" to "My Test",
        "test_session_name" to "My Session"
    ))
    //.dryRun()
    .newRule()

The TrackingplanRule will initialize the SDK before each test is executed, ensuring all the collected data is sent to Trackingplan after every test execution. Note that this rule will overwrite any existing initialization of Trackingplan SDK for Android in your app.

← Previous

Webhooks

Post-Install Warm-Up