Skip to content

Latest commit

 

History

History
523 lines (521 loc) · 26.1 KB

PredefinedVariables.md

File metadata and controls

523 lines (521 loc) · 26.1 KB

alt tag

Predefined variables Guide

SDK TagCommander Android and iPhone

Last update : 15/07/2022

Predefined variables

The following document is the complete, up-to-date, list of all predefined variables that Tag Commander's SDK automatically generates.

For each of them we give you a small description of the variable and an example on at least one Android device and one iOS device. We might show more example if needed.

The name in parentheses present the old names. They can still be used in v3 configurations, but are deprecated and such should not be. Starting v4, they have been completely removed.

#TC_IP# (#IP#)

/!\ Require user consent.

The ip address of the device. Only available if the device is connected to internet.

  • Galaxy Tab 3: 10.144.112.50
  • iPhone 4s: 10.144.112.88

#TC_EMPTY# (#EMPTY#)

An empty predefined variable if needed. Please note that any variable defined in your configuration will be empty if no value is given during implementation.

  • Nexus 7:
  • iPhone 5:

#TC_RAND# (#RAND#)

A random number that can be used for various purposes.

  • OnePlus One: 1999907613
  • iPhone 5: 861518817

#TC_LANGUAGE# (#TC_LOCAL_LANGUAGE#)

The localised language of the device.

  • Nexus 7: fr_CA
  • iPhone 4s: fr_FR

#TC_LANGUAGE_CS# (#TC_LOCAL_LANGUAGE_CS#)

The localised language of the device formatted especially for ComScore.

  • Nexus 7: fr
  • iPhone 4s: fr

#TC_LANGUAGE_GA# (#TC_LOCAL_LANGUAGE_GA#)

The localised language of the device formatted especially for Google Analytics.

  • Nexus 7: fr-CA
  • iPhone 4s: fr-FR

#TC_SYSNAME# (#TC_LOCAL_SYSNAME#)

The full system name of the device.

  • Galaxy Tab 3: android-4.2.2
  • iPhone 4s: iPhone OS

#TC_SYSVERSION# (#TC_LOCAL_SYSVERSION#)

Only the system version of the device.

  • Galaxy Tab 3: 4.2.2
  • iPhone 4s: 8.4.1

#TC_MODEL# (#TC_LOCAL_MODEL#)

The name of the device's model.

  • Nexus 7: Nexus 7
  • OnePlus One: A0001
  • Galaxy S3: GT-I9305
  • iPhone 4s: iPhone

#TC_MODEL_AND_VERSION# (#TC_LOCAL_MODEL_AND_VERSION#)

This returns the model and the version of the phone depending on the device code. It only exists in iOS.

  • iPhone 5s: iPhone 5S

#TC_CONNEXION# (#TC_LOCAL_CONNEXION#)

The way the device is connected to the internet.

  • Galaxy Tab 3: MOBILE
  • iPhone 5: WIFI

#TC_DEVICE

/!\ Require user consent.

The name of the device as given by its owner.

  • Galaxy Tab 3: lt01wifi
  • Nexus 7: flo
  • iPhone 4s: iPhone4,1

#TC_SCREEN# (#TC_LOCAL_SCREEN#)

The screen resolution of the device.

  • Galaxy Tab 3: 1920x1104
  • iPhone 4s: 320x480

#TC_CHARSET# (#TC_LOCAL_CHARSET#)

The character encoding used by default on the device.

  • OnePlus One: UTF-8
  • iPhone 5: MacRoman

#TC_CURRENCY_CODE

The code of the currency used by default on the user device.

  • OnePlus One: EUR
  • iPhone 4s: CAD

#TC_CURRENCY_SYMBOL

The encoded symbol of the currency used by default on the user device.

  • OnePlus One: €
  • iPhone 4s: $

#TC_APPLICATION_VERSION# (#TC_LOCAL_APPVERSION#)

The version of the application which is running the SDK.

  • Nexus 7: 42.2.12
  • iPhone 5: 2.4

#TC_APPLICATION_PREVIOUS_VERSION

The previous version number of the application if available. Empty otherwise.

  • Nexus 7: 42.2.10
  • iPhone 5: 2.1

#TC_APPLICATION_BUILD

The application build number.

  • Nexus 7: 1536
  • iPhone 5: 2.3

#TC_TAGCOMMANDER_VERSION

The version of Tag Commander's SDK. It's formatted as follow: "version.release-date".

  • OnePlus One: 3.1.2015-10-16
  • iPhone 4s: 3.1.2015-10-16

#TC_MANUFACTURER

The name of the device's manufacturer.

  • Galaxy Tab 3: samsung
  • OnePlus One: OnePlus
  • iPhone 4s: Apple

#TC_USER_AGENT

/!\ Require user consent.

The user agent of the device's web browser.

  • OnePlus One: Mozilla/5.0 (Linux; Android 4.4.4; A0001 Build/KTU84Q) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/33.0.0.0 Mobile Safari/537.36
  • Galaxy Tab 3: Mozilla/5.0 (Linux; U; Android 4.2.2; fr-fr; SM-T310 Build/JDQ39) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Safari/534.30
  • iPhone 5: Mozilla/5.0 (iPhone; CPU iPhone OS 8_4_1 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12H321

#TC_JAILBROKEN

Return if the device seems Jailbroken or rooted. There exist many algorythm to detect it, and the methods used to root or jailbreak a phone change over time. This variable is thus not 100% accurate. Also please note that simulators tends to return that they are jailbroken or rooted.

  • Galaxy S3: 0
  • iPhone 4s: 0
  • simulator iPhone 6s: 1

#TC_APPLICATION_STARTS

The number of cold launch of the application. A cold start is when the application is launched while it wasn't previously in memory.

  • Galaxy S3: 19
  • iPhone 4s: 1

#TC_FOREGROUNDS

Indicates how many times the application switch to foreground. An application is in foreground when the user is using it. Should be at least one, since during launch the application is considered as going into foreground.

  • Nexus 7: 1
  • iPhone 6: 5

#TC_FOREGROUND_TIME

The duration spent in the application while in foreground. This time is indicated in milliseconds.

  • Galaxy Tab3: 40375
  • iPhone 5: 125262

#TC_DELTA_FOREGROUND_TIME

The delta between now and the last time a foreground time measurement was sent by Tag Commander. This is also indicated in milliseconds.

  • Galaxy Tab3: 4013
  • iPhone 5: 1618

#TC_BACKGROUND_TIME

The duration spent in background. This time is given in milliseconds.

  • Galaxy S3: 13698
  • iPhone 6: 54691

#TC_DELTA_BACKGROUND_TIME

The delta between now and the last time a background time measurement was sent by Tag Commander. It is also in milliseconds.

  • Galaxy S3: 733
  • iPhone 6: 9257

#TC_BACKGROUND_UX_TIME

The duration the application spent in background while presenting an interactive content to the user. It is presented in milliseconds.

  • Nexus 7: 12001
  • iPhone 4s: 15354

#TC_DELTA_BACKGROUND_UX_TIME

The delta between now and the last time an UX background time measurement was sent by Tag Commander. Still in milliseconds.

  • Nexus 7: 1211
  • iPhone 4s: 871

#TC_CURRENT_CALL# (#TC_NAV_TIMESTAMP_CURRENT_CALL#)

The timestamp of the hit. It is classic unix timestamp, which is seconds since 1970. It is measured the moment the hit is created, if the device is offline, when the hit is sent, this timestamp will still represent the time the hit was created.

  • Nexus 7: 1444987160
  • iPhone 4s: 1444987175

#TC_CURRENT_CALL_MS# (#TC_NAV_TIMESTAMP_CURRENT_CALL_MS#)

Same as the previous one, but in milliseconds.

  • Nexus 7: 1444987160642
  • iPhone 4s: 1444987175973

#TC_LAST_CALL# (#TC_NAV_TIMESTAMP_LAST_CALL#)

The time when the previous call was made. Here also it is the time when the hit was recorded which is not necessarily the time when he was sent. This is represented as seconds since 1970.

  • Nexus 7: 1444987141
  • iPhone 4s: 1444987138

#TC_LAST_CALL_MS# (#TC_NAV_TIMESTAMP_LAST_CALL_MS#)

Same as the previous one, but in milliseconds.

  • Nexus 7: 1444987141577
  • iPhone 4s: 1444987138626

#TC_LAST_SESSION_LAST_HIT

This time represents the timestamp of the last hit recorded during the previous session. A changed of session is either defined by a long time spent in background (currently 30 minutes) or by a new cold start.

  • Nexus 7: 1444987089
  • iPhone 4s: 1444987073

#TC_LAST_SESSION_LAST_HIT_MS

Same as the previous one, but in milliseconds.

  • Nexus 7: 1444987089372
  • iPhone 4s: 1444987073163

#TC_NOW

The unix formatted timestamp (seconds since 1970) from when you ask it.

  • Nexus 7: 1444987160
  • iPhone 4s: 1444987175

#TC_NOW_MS

Same as the previous one, but in milliseconds.

  • Nexus 7: 1444987160642
  • iPhone 4s: 1444987175973

#TC_UNIQUEID# (#TC_LOCAL_UNIQUEID#, #TC_NAV_VISITOR_ID#)

Android: A 64-bit number (as a hex string) that is randomly generated when the user first sets up the device and should remain constant for the lifetime of the user's device. The value may change if a factory reset is performed on the device.

iOS: A unique UUID generated during the first install on the phone. This will change if the application is uninstalled then re-installed. This won't change if the user resets his IDFA.

  • OnePlus One: a284d098fdf1c342
  • iPhone 4s: 80EF0DC8-AD1B-460A-AC2D-4646FA2356E3

#TC_IDFA# (Android : Removed from 4.6.0+)

/!\ Require user consent.

The advertising identifier as specified by either Google or Apple.

  • Nexus 7: a4ca013b-218b-4a9b-818e-8d1a751b39bf
  • iPhone 5: 3385ACC1-D465-2D13-A4E3-9A5A865A232C

Can be resetted by the user in the phone's system. If it is, the value will be: - 00000000-0000-0000-0000-000000000000

#TC_IDFV

/!\ Require user consent.

The advertising ID for the vendor (unique by vendor). Only available on iOS and formatted as an UDID.

  • iPhone 4s: 6480CCA0-AEFC-2100-B5C6-ABCF01AA3721

#TC_IS_TRACKING_ENABLED# (Android : Removed from 4.6.0+)

Is tracking enabled on the device. This can be turned off by the user manually in the device's settings.

  • Galaxy S3: false
  • iPhone 5: NO

#TC_LIMIT_USER_TRACKING_ENABLED# (Android : Removed from 4.6.0+)

Is the user limiting the tracking on his device. This is effectively this inverse of #TC_IS_TRACKING_ENABLED#.

  • Galaxy S3: true
  • iPhone 5: YES

#TC_LONGITUDE# (iOS: Before SDK 4.4.1)

/!\ Require user consent.

The longitudinal position of the user using the device. It won't be available if the user turned off all means of localisation.

This Variable requires you to ask permission to use location to your users.

  • Galaxy Tab3: 2.3263269
  • iPhone 4s: 2.2311654

#TC_LATITUDE# (iOS: Before SDK 4.4.1)

/!\ Require user consent.

The latitudinal position of the user using the device. It won't be available if the user turned off all means of localisation.

This Variable requires you to ask permission to use location to your users.

  • Galaxy Tab3: 48.8708206
  • iPhone 4s: 48.8765126

#TC_BUNDLE_IDENTIFIER

The bundle identifier of the application running Tag Commander.

  • OnePlus One: com.tagcommander.tcdemo.tcdemo
  • iPhone 4s: com.tagcommander.test.TCDemo

#TC_APPLICATION_NAME

The name of the application running Tag Commander.

  • OnePlus One: TCDemo
  • iPhone 4s: TCDemo

#TC_RUNTIME_NAME

The name of the runtime of the device.

  • Galaxy Tab3: android
  • iPhone 5: ios

#TC_FIRST_VISIT# (#TC_NAV_TIMESTAMP_FIRST_VISIT#)

The timestamp of the first launch of the application in seconds.

  • Nexus 7: 1426775262
  • iPhone 4s: 1426775262

#TC_FIRST_VISIT_MS# (#TC_NAV_TIMESTAMP_FIRST_VISIT_MS#)

The timestamp of the first launch of the application in milli-seconds.

  • Nexus 7: 1426775262470
  • iPhone 4s: 1426775262470

#TC_LAST_VISIT# (#TC_NAV_TIMESTAMP_LAST_VISIT#)

The timestamp of the start of the last visit of the application in seconds. It's equal to the first visit during the fist launch.

  • Nexus 7: 1427449277
  • iPhone 4s: 1427449277

#TC_LAST_VISIT_MS# (#TC_NAV_TIMESTAMP_LAST_VISIT_MS#)

The timestamp of the start of the last visit of the application in milli-seconds. It's equal to the first visit during the fist launch.

  • Nexus 7: 1427449277881
  • iPhone 4s: 1427449277881

#TC_CURRENT_SESSION# (#TC_TIMESTAMP_CURRENT_VISIT#)

The timestamp of current session in seconds. It's equal to the first visit during the fist launch.

  • Nexus 7: 1427449428
  • iPhone 4s: 1427449428

#TC_CURRENT_SESSION_MS# (#TC_TIMESTAMP_CURRENT_VISIT_MS#)

The timestamp of current session in milli-seconds. It's equal to the first visit during the fist launch.

  • Nexus 7: 1427449428069
  • iPhone 4s: 1427449428069

#TC_CURRENT_VISIT# (#TC_NAV_TIMESTAMP_CURRENT_VISIT#)

The timestamp of current visit in seconds. It's equal to the first visit during the fist launch.

  • Nexus 7: 1427449428
  • iPhone 4s: 1427449428

#TC_CURRENT_VISIT_MS# (#TC_NAV_TIMESTAMP_CURRENT_VISIT_MS#)

The timestamp of current visit in milli-seconds. It's equal to the first visit during the fist launch.

  • Nexus 7: 1427449428069
  • iPhone 4s: 1427449428069

#TC_SESSION_DURATION

The duration of current session in seconds. A session is defined as either a new launch or as a foreground after having spent more than 30 minutes in background.

  • Galaxy S3: 40
  • iPhone 5: 31

#TC_SESSION_DURATION_MS

The duration of current session in milli-seconds. A session is defined as either a new launch or as a foreground after having spent more than 30 minutes in background.

  • Galaxy S3: 40613
  • iPhone 4s: 31664

#TC_VERSION_FIRST_VISIT_MS# (#TC_NAV_TIMESTAMP_VERSION_FIRST_VISIT_MS#)

The first timestamp (in milli-seconds) of the first session run with the current version of the application. This changes everytime the application gets updated.

  • Galaxy S3: 1427376462695
  • iPhone 4s: 1427376462695

#TC_NUMBER_VISIT# (#TC_NAV_NUMBER_VISITS#)

The number of times the user visited the application.

  • OnePlus One: 16
  • iPhone 4s: 2

#TC_NUMBER_SESSION

The number of times a session got created for this application.

  • OnePlus One: 21
  • iPhone 4s: 2

#TC_EMPTY_VARIABLE_REMOVE_EQUAL

This variable only exist in v3 and before of Tag Commander's SDK.

A special predefined variable which removes the '=' sign in the query string if the variable is not defined. It was created to answer a special case for google analytics.

#TC_IS_FIRST_VISIT

This is a very simple variable that is TRUE during the whole duration of the fist launch of the application, and FALSE the next times the app will be launched.

  • Galaxy S7: TRUE
  • iPhone 6s: FALSE

#TC_FIRST_EXECUTE

The first time you ask the SDK to either execute() or SendData() each hard launch, this variable is TRUE and it's FALSE otherwise.

It can be combined TC_IS_FIRST_VISIT, to have the very first hit of the first launch of the application.

  • OnePlus One: FALSE
  • iPhone 4s: TRUE

#TC_INSTALL_REFERRER# 4.0+

Android Only

Two way to get the install referrer exists. The first is to use this variable, it will give you the whole referrer string as given by Google. The second one is when you know exactly what to expect, all part of the referrer URL will be transformed as variables.

Android: #TC_INSTALL_REFERRER# = utm_source=google&utm_medium=cpc&utm_term=running%252Bshoes&utm_content=displayAd1&utm_campaign=shoesshoesshoes

#utm_source# = google

#utm_medium# = cpc

#utm_term# = running%252Bshoes

#utm_content# = displayAd1

#utm_campaign# = shoesshoesshoes

#TC_SDK_ID# Core 4.1.3+

An ID formatted as an UUID created by the SDK to be unique. It can't be resetted by the user, but if the user remove the application and install it again later, it will have a different ID.

  • OnePlus One: 65343D4C-BE71-47BC-B60A-4A46E49ED87E
  • iPhone 6: 80EF0DC8-AD1B-460A-AC2D-4646FA2356E3

#TC_NORMALIZED_ID# Core 4.1.3+ (Android : Removed from 4.6.0+)

/!\ Require user consent.

An special ID mixing IDFA/AAID and TC_SDK_ID. Some user disable the IDFA/AAID, but those IDs are still the most reliable to recognize a user, to remove the need of manually checking the IDs we created a mix.

TC_NORMALIZED_ID will be equal to the IDFA/AAID if the user has one, but if not, instead of having an empty IDFA, you will have the TC_SDK_ID. Coupled together you can also gain insight on the reliability of those ID when trying to identify users in the long run. Since if this ID is equal to the IDFA, you can match this ID with IDFA from other users coming from different sources.

  • OnePlus One: 65343D4C-BE71-47BC-B60A-4A46E49ED87E
  • iPhone 6: 3E115C1E-CFC9-4A31-A7AE-D5FD45C9541C