Glossary

Last Updated: Jan 25, 2017 01:54PM PST

Contents



Attribution Tracking Tags
After a successful SDK or API integration, Attribution Tracking Tags can be automatically generated for integrated Ad Networks or custom sources.  Apsalar SmartTags, a new and simplified way of attribution tracking tag management, enhance Apsalar standard Attribution Tracking Tags with additional features.  See more information on Apsalar SmartTags here.  

Standard Apsalar Attribution Tracking Tags can include a variety of information as listed below.  With the SmartTags, some of these parameters are consolidated and not available.

Base URL: http://ad.apsalar.com/api/v1/ad?
 
Parameter Value Example In Tracking Tags In SmartTags
SmartTag Parameters
st SmartTag ID st=544783522947 No Yes
Account Parameters
a Apsalar account ID a=SampleAccountName Yes No
h Apsalar's assigned security hash h=e35c3d9c098983a0caac36c94a971219238bd7 Yes Yes
Application Parameters
i Application bundle ID i=com.SamplePub.SampleApp Yes No
p Platform (iOS or Android) p=Android Yes No
Campaign Parameters
ca Apsalar campaign name ca=SampleCampaign Yes No
pl Apsalar campaign group name pl=SampleGroup Yes No
s Source application or site s=SampleSourceAppName If available If available
cl Click ID assigned by Ad Network cl=SampleClickID_1234 Recommended Recommended
cr Creative's name cr=MyCreativeName Optional Optional
wd Creative's width wd=400 Optional Optional
ht Creative's height ht=200 Optional Optional
re Re-engagement Tracking. Should be set to '1' if tracking re-engagement, '0' if not. re=0 Optional Optional
Device Parameters
Note: device parameters and values are required for re-engagement tracking tags (re=1).  For more information on re-engagement tracking, click here
idfa Advertising Identifier in RAW format - iOS only idfa=A1C252F5-46AB-4175-9162-EFA23391D9DF Recommended Recommended
ifa1 SHA1 of IDFA - iOS only ifa1=9a96aedd6d9b5717f7ba3e4bb454add4ae25a980 If available If available
ifa5 MD5 of IDFA - iOS only ifa5=9a96aedd6d9b5717f7ba3e4bb454add4ae25a980 If available If available
andi Android ID - Android only andi=2a9ca2cf2668d55a If aifa is not available If aifa is not available
and1 SHA1 of Android ID and1=3272791617360a44edd7a07582ae21a6768fa1fc If aifa is not available If aifa is not available
and5 MD5 of Android ID and5=f64f435d04b9736827b2157d6353314d If aifa is not available If aifa is not available
aifa Android Advertising ID aifa=A1A111A8-0AAA-000A-A00A-000000000000 Recommended Recommended
aif1 SHA1 of Android Advertising ID aif1=2f7023424973d529a26c11cb49bb24ee4d37f87f If available If available
aif5 MD5 of Android Advertising ID aif5=d2a8149dadb68447c9dc2fc56f8e4a82 If available If available
ip IP address of device ip=10.10.10.10 Optional Optional
ve OS version ve=6.1.3 Optional Optional

Carrier
The wireless carrier used by your application’s user. (e.g., Sprint, T-Mobile, Verizon, WiFi)
 
Click-Through Attribution
A measure of success with respect to users downloading and installing the application.  It is assumed that the click led to the download, and that installation is attributed to that specific ad.  Typical click-through attribution windows is 30 days.  Click-through attributions take precedence over view-through attributions.
 
Cohort  
A group of unique users who share a common characteristic or experience within an application or applications over a defined period of time, as opposed to across all time.  Cohort reporting is available in the advertiser dashboard here

Conversion
The action of a unique user achieving a specific goal (event) in an application. Examples of a conversion goal could include a product purchase, making a reservation, making a financial transaction, etc.

Conversion Rate
A measure of success with respect to users taking a desired action (goal) within the application. The conversion rate (CVR) is the ratio of unique users who reach the goal divided by the total number of unique users of the application. More specifically, Apsalar uses the CVR as part of conversion funnels analyses and in this case, the CVR is calculated with respect to unique users who have entered the funnel.

Daily Active User (DAU)
A user is counted as DAU for every day of a specific application session.  For instance, if a user starts a session on May 1 and ends the session on May 4, they will be counted as a DAU for May 1, 2, 3, and 4. Their activity is measured by the session start and end time, which is affected by event activity, heartbeat counts, and the actual end session.   Note that if they have the app in the background during the period of the session, say for May 2, and return to the foreground in May 3, they will  be counted as active for May 2 since the session had not actually ended.

Device
The brand name identifier for a specific mobile device (e.g, HTC Incredible, Nokia 6600)

Event
Any user action, state change, or other occurrence that has been instrumented in an application and is being tracked by Apsalar's SDK/API.

First Time User
A unique user who has started a specific application for the first time. This user is a first time user only once. If their session ends and they restart the app, they are then tracked as a returning user.

Funnel
A sequence of steps (events) that a user is expected to take in order to reach a specific conversion goal. Once an application user triggers any step in the funnel, they are considered to have entered the funnel. From that point on, their behavior can be tracked and conversion rates between funnel steps and overall funnel conversion rates can be calculated

Organic Install
An install for an application that was not credited to either an ad click, nor ad impression/view.  This is considered unpaid and non-promoted traffic into your application.

Platform
A mobile device’s Operating System. In the case of Apsalar, we track behavior for all versions of iOS and Android.

Passthrough Parameters
During the Ad Network integration process, Ad Networks can provide passthrough parameters to Apsalar that they wish to receive in their attribution postback. These values can be passed through on any parameter not listed in the table for Attribution Tracking Tags. A common passthrough parameter is often an Ad Network's internal advertiser ID, e.g. aid=115873. These parameters must be stated when setting up the integration in order to be available for the attribution postback.

Passthrough parameters can also be used by the advertiser to supply custom information in the attribution tracking tag that they wish to receive in postbacks to their own servers.

Postbacks and Postback Macros
A Postback is the URL which a user or Ad Network designates as an endpoint for notification. For example, upon a successful installation resulting from a campaign, Apsalar will call a designated install postback to alert the Ad Network to the conversion. Apsalar supports the following macros in Postbacks:
 
Macro Value
Application Related Macros
{APP_NAME} Display Name of application
{LONGNAME} Long name (bundle ID) of application
Campaign Macros
{CID} Campaign Name as specified in Attribution Tracking Tags
{CLID} Apsalar assigned click ID (string)
{CREATIVE} Creative ID - Available only if provided in click.
{GID} Group Name as specified in Attribution Tracking Tags
{SITE} Source site or application for click(string). Available if passed in click.
{NETWORK} Name of network to which install is attributed, when available
{NETWORK=Network Name} Will return '1' if network is equal to specified Network Name, '0' if not. Please note, network name must be exactly the same as the Campaign Source specified in the Attribution Tracking Tag. For example, an install attributed to Tapjoy would return a '1' for {NETWORK=Tapjoy}, but a '0' {NETWORK=tapjoy}.
{IS_RE_ENG} Will return '1' if attributed to a re-engagement campaign, '0' if not.
Device Related Macros
{IP} IP of the device at the time of the clicked ad
{OS_VERSION} OS version of the device at the time of the clicked ad
{APP_VERSION} App version of the device at the time of the install/event
{IDFA} Unhashed iOS advertising identifier of device
{IFA1} SHA-1 of iOS advertising identifier of device
{IFA5} MD5 of iOS advertising identifier of device
{IDFV} Unhashed iOS identifier for vendor
{ANDI} Unhashed Android ID - this identifier is available if the advertising identifier (AIFA) is not available on the device.  As this identifier is not always available, we recommend using {AIFA}, or {COALESCE|{AIFA},{ANDI}} to ensure a value is always passed.
{AND1} SHA1 of Android ID
{AIFA} unhashed Android advertising identifier of device
{AIF1} SHA-1 of Android advertising identifier of device
{AIF5} MD5 of Android advertising identifier of device
{COALESCE} Pass one ID or the other. Example: {COALESCE|{AIFA},{ANDI}} will let you pass AIFA or ANDI (if AIFA is not available)
{PLATFORM} iOS or Android
{COUNTRY} Country from which user installed
{APID} Apsalar internal ID (string).
{USERID|user.key} Custom user ID. Replace key with the key of the custom user ID key-value pair. For example, where the key-value is balloonjumpID=username, the macro should be {USERID|user.balloonjumpID}. This will be replaced with 'username'.
{DNT} Do not track flag is set active a 1 will be returned, all other conditions will return 0
{NODNT} Do not track flag is set active a 0 will be returned, all other conditions will return 1
{DEVICE_MODEL} Device model
{DEVICE_BRAND} Device Brand
{MATCH_TYPE} Indicates whether and attribution is Organic (null value), deterministic (device id matching) or with fingerprinting methodology
Event Macros
{AMOUNT} Revenue event postbacks only - The transaction amount in dollars and cents
{CURRENCY} Revenue event postbacks only - The three-letter ISO 4217 currency code for the transaction
{EVTNAME} Name of the event
{EVTATTR:Attribute_Name} Value from the specified attribute. For example if you have an event named 'Checkout' with an attribute 'Number of Items', then {EVTATTR:Number of Items} would return the number of items from the 'Checkout' event.
{IS_FIRST_EVENT} Returns '1' for first occurrence of an event (revenue or custom), '0' for every subsequent event from the same device ID.
Facebook Macros
{FB_C_ID} Numeric Facebook Campaign ID. Subject to restrictions based on Facebook's terms of service.
{FB_C_NAME} Facebook Campaign name. Subject to restrictions based on Facebook's terms of service.
{FB_AS_ID} Numeric Facebook Ad Set ID. Subject to restrictions based on Facebook's terms of service.
{FB_AS_NAME} Facebook Ad Set name. Subject to restrictions based on Facebook's terms of service.
{FB_A_ID} Numeric Facebook Ad ID. Subject to restrictions based on Facebook's terms of service.
{FB_A_NAME} Facebook Ad name. Subject to restrictions based on Facebook's terms of service.
Twitter Macros
{TWTR_C_NAME} Twitter Campaign Name. Subject to restrictions based on Twitter's terms of service.
{TWTR_C_ID} Twitter alphanumeric Campaign ID. Subject to restrictions based on Twitter's terms of service.
{TWTR_G_ID} Twitter alphanumeric Line Item ID. Subject to restrictions based on Twitter's terms of service.
{tweet_id} Tweet ID - Applicable to organic twitter installs only.
Apsalar suggests the following convention for capturing the Tweet ID for Twitter associated installs: your_parameter={CREATIVE}{tweet_id}
This will capture the Tweet ID value for installs attributed to Twitter Campaigns and organic Twitter installs.
Time Macros
{DATE} Install or event date (string formatted as "YYYYMMDD") in GMT timezone
{TIME} Install or event timestamp (string formatted as "YYYY-MM-DD_HH:MM:SS") in GMT timezone
{UTC} Install or event timestamp in UNIX format in seconds 
{UTCM} Install or event timestamp in UNIX format in milliseconds
{CLICK_UTC} Click timestamp in UNIX format in seconds
{CLICK_UTCM} Click timestamp in UNIX format in milliseconds
{CLICK_TIME} Click timestamp (string formatted as "YYYY-MM-DD_HH:MM:SS") in GMT timezone
{CLICK_DATE} Click timestamp (string formatted as "YYYYMMDD") in GMT timezone
{INSTALL_UTC} Install timestamp in UNIX format in seconds
{INSTALL_UTCM} Install timestamp in UNIX format in milliseconds
{INSTALL_TIME} Install timestamp (string formatted as "YYYY-MM-DD_HH:MM:SS") in GMT timezone
{INSTALL_DATE} Install timestamp (string formatted as "YYYYMMDD") in GMT timezone
{STRFTIME|<constructing values>,ts (optional),round (optional)} Constructable timestamp. The timestamp can be constructed using the following defined values and any additional desired characters:
  • %d - Day of month as a zero-padded number (01, 02,...,31)
  • %m - Month as a as a zero-padded number (01, 02,...,12)
  • %Y - Year with four digits (2014)
  • %H - Hour in 24 hour format
  • %I - Hour in 12 hour format (the letter is i in caps)
  • %M - Minute as a zero padded number (00, 01,...,59)
  • %S - Second as a zero padded number (00, 01,...,59)
For example, {STRFTIME|%Y-%m-%dT%H:%M:%S} would populate like so: 2014-08-22T10:06:52

"ts" is an optional UNIX timestamp which will be used for the formatting; if no "ts" is specificed, the current time is used.  Supported "ts" values are {CLICK_UTC}, {INSTALL_UTC}, and {UTC}. 

For example, {STRFTIME|%Y-%m-%dT%H:%M:%S,{UTC}}

"round" is an optional modified which will truncate/round to one of the following: year, month, day, hour, or minute

For example if {CLICK_UTC} is 1435627795:
{STRFTIME|%s,{CLICK_UTC},month} -> 1433116800
{STRFTIME|%s,{CLICK_UTC},day} -> 1435622400
{STRFTIME|%s,{CLICK_UTC},hour} -> 1435626000
{STRFTIME|%s,{CLICK_UTC},minute} -> 1435627740
Other Macros
{RAND} Random 10 character integer
{JSON} Used to convert the request from GET to POST with a JSON payload. Everything to the left of that macro is evaluated normally, but the part to the right is removed from the URL, converted into a JSON dictionary equivalent to the query string parameters, and we perform a HTTP POST to the URL left of the {JSON} macro.
{POST} Similar to the {JSON} macro, except the payload is sent using the older application/x-www-form-urlencoded encoding.
{HTTP_HEADER|k,v} Add a single key/value pair to the HTTP header using this macro. Add additional key/value pairs by adding additional instances of the macro, e.g.  {HTTP_HEADER|SampleKey1,SampleValue1}{HTTP_HEADER|SampleKey2,SampleValue1}.
This macro will be used to populate the header and will be completely removed from the URL when sent, so do not add any additional characters such as '&' or '?' when adding this macro to the URL, e.g.
​https://theURL.com/endpoint?{HTTP_HEADER|SampleKey1,SampleValue1}apsalar_cl={CLID}&andi={ANDI}{HTTP_HEADER|SampleKey2,SampleValue2}
Macro Modifiers
{SHA1|{Macro}} Modifier will encode the value as SHA-1. For example, if the {CLID} macro returned '1000', {SHA-1|{CLID}} would return 'fb2f85c88567f3c8ce9b799c7c54642d0c7b41f6'.
{MD5|{Macro}} Modifier will encode the value as MD5. For example, if the {CLID} macro returned 'ABCD', {MD5|{CLID}} would return 'cb08ca4a7bb5f9683c19133a84872ca7'.
{BASE64|{Macro}} Modifier will encode the value as standard Base64. For example, if the {CLID} macro returned 'ABCD', {BASE64|{CLID}} would return 'QUJDRA=='. (The returned value will be HTTP encoded in the URL)
{BASE64U|{Macro}} Modifier will encode the value as url-safe Base64. For example, if the {CLID} macro returned 'ABCD', {BASE64U|{CLID}} would return 'QUJDRA=='. (The returned value will be HTTP encoded in the URL)
{HMACSHA1|{Macro},key} Modifier will encode the value as HMAC SHA-1 using the provided key. For example, if the {CLID} macro returned 'ABCD', {HMACSHA1|{CLID},sample} would return 'f5143f3dda1b120ac280a82b2cae0ff60dc342b5'.
{HMACMD5|{Macro},key} Modifier will encode the value as HMAC MD5 using the provided key. For example, if the {CLID} macro returned 'ABCD', {HMACMD5|{CLID},sample} would return '43d752ccec4044f90a66a7d15762075e'.
{UPPER|{Macro}} Modifier will return the provided value in upper case characters. For example, if the {CLID} macro returned 'abcd', {UPPER|{CLID}} would return 'ABCD'.
{LOWER|{Macro}} Modifier will return the provided value in lower case characters. For example, if the {CLID} macro returned 'ABCD', {LOWER|{CLID}} would return 'abcd'.
{MULTIPLY|{Macro},multiple} Modifier will multiply the number by the value returned by the macro to the nearest whole number.  To convert the value of a product purchase in floating point to micro it requires multiplying the {AMOUNT} macro 1e6 (1000000). For example, a $5250.23 purchase would become 5250230000 when formatted as {MULTIPLY|5240.23,1000000}.

Repeat User
A unique user who has used a specific app at least one time, ended a session, and then restarted the application.

Revenue
A measure of a user’s monetization events with an application.  Revenue can be associated with one or more event by selecting a revenue attribute for the event.  Apsalar analytics can then use this information with respect to overall revenue and average revenue per user (ARPU).

Session
The period from when a unique user starts an application and that application then starts an Apsalar session to the time when the user either completely quits the application or the application code uses the Apsalar API explicitly to end the session. For example, a user who has the application running in the background has not ended a session, unless the application itself ends it when it goes into the background. The Apsalar API can be used to start, end, and restart sessions, giving the application developer the ability to control the definition of a session.

Session Length
The amount of time that a user has spent in a session. A user’s session length will be extended (timestamped) upon the recording of an instrumented event, Apsalar heartbeat, or an endSession event.

Unique User
A unique user is identified through the UDID of the phone upon which the application is running. Many reports provide the ability to look at data for unique users, attributing user behavior within an application to specific users.
 
View-Through Attribution
A measure of success with respect to users downloading and installing the application.  It is assumed that an ad view/impression led to the download, and that installation is attributed to that specific ad.  Typical view-through attribution windows is 24 hours.  View-through attributions are considered after click-through attributions, but above organic installs.
support@apsalar.com
http://assets1.desk.com/
apsalarinc
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
Invalid characters found
/customer/en/portal/articles/autocomplete