# Advanced

The following are tips for advanced use cases.

# Override Properties

You may explicitly set or override properties and have then be recalled even in subsequent user visits where the original or full context may not be available.

// Examples: bta('set{PropertyName}')

// Sets UserId. If property is not defined in subsequent
// data, it will still be populated from the previous value
// Note: getRequest() is just a placeholder function that 
// returns the data like: 
// return { currency: "USD", value: 1234.56}
bta('setUserId', "mynewuserid");
bta('download', {...getRequest(), userId: undefined});

# Send Data for Multiple Keys

You may send data to multiple keys.

// multiple keys
bta('registerKey', '{{ KEY_1 }}');
bta('registerKey', '{{ KEY_2 }}');
bta('registerKey', '{{ KEY_3 }}');
bta('registerKey', '{{ KEY_1 }}');
// remove 'KEY 1' from receiving data
bta('unregisterKey', '{{ KEY_1 }}');
// will send data to both 'KEY_2' and 'KEY_3'
bta('lead', getRequest());

// send data only for 'KEY_1'
bta('viewitem', getRequest(), '{{ KEY_1 }}')
// send data event only for 'KEY_2'
bta('viewitem', getRequest(), '{{ KEY_2 }}')

# Selective Data for Multiple Keys

You may send different data to different keys.

// send one event only for 'KEY_1'
bta('viewitem', getRequest1(), '{{ KEY_1 }}')
// send one event only for 'KEY_2'
bta('viewitem', getRequest2(), '{{ KEY_2 }}')
// send one event with the intial config key from 
// the install/page load
bta('viewitem', getRequest1())

# Callbacks

If you need to run code after the data is sent, you may execute callbacks.

// Run callback/execute code on success
function withcallbacksuccess() {
  window['onBacktracksAttributionSuccess'] = function (result) {
    console.log('Success:', result);
    window['onBacktracksAttributionSuccess'] = undefined;
  };

  bta('purchase',
    // ...
  );
};

// Run callback/execute code on failure
function withcallbackfailure() {
  window['onBacktracksAttributionFailure'] = function (result) {
    console.log('Failure:', result);
    window['onBacktracksAttributionFailure'] = undefined;
  };

  bta('addtocart',
    // ...
  );
};

# Delay Event Fires

If you want to delay the recording of events to do something like only track data for engaged visitors or after N seconds on a page you can accomplish this by adding a delay with setTimeout.

// Delay by N seconds
var seconds = 5;
setTimeout(function() {
  bta('viewitem', 
    // ...
  );
}, seconds * 1000);

# Install Using IMG Tag or Pixel

In cases where you cannot execute JavaScript, you may install and run the Backtracks Attribution tracker with a HTML <img> tag or pixel.

<img src="https://api.backtracks.fm/v1/attribution/image?k=YOUR_BT_KEY
  &e=purchase
  &d[transactionId]=dd5b098d-f628-4076-9b2a-7020e8fe1f57
  &d[discountCode]=abc-123
  &d[value]=1234.56
  &d[currency]=USD" 
  height="1" width="1" style="display:none"/>

To fire a purchase event for example, you may construct an event similar to the following, while passing in any custom parameters that are applicable to your scenario.

<img height="1" width="1" style="display:none" 
 src="https://api.backtracks.fm/v1/attribution/image?k=abc123&e=purchase&d[currency]=USD&d[value]=123.45&d[tax]=1.23&d[shipping]=1.24&d[transactionId]=67ebba62-5534-4048-b74a-9e6ff15bd90a" />

If the <img> tag is loaded within an iframe that is sandboxed with the sandbox attribute, then allow-scripts property must be added to the iframe.

<iframe src="https://example.com/example-iframe-with-img-tag" sandbox="allow-scripts"></iframe>

# Track Ad Impressions via Serverside or API

Backtracks can track campaign and ad impression data for podcasts, streaming audio, digital radio, etc. for any ad campaign or ad buy. In cases where ads are served dynamically, through a listening platform, or pings for ad impressions can/should be sent serverside, the Backtracks Ad Impression API may be utilized. This is also called a tag/pixel.

If you are setting up or purchasing ads in a listening app or platform, you or your account manger may configure measurement and tracking calls to Backtracks for any of your ad campaigns and ads.

https://api.backtracks.fm/v1/tracking/pixel?k=YOUR_BT_KEY
&e=impression
&d[campaignId]=79af8773-a058-4f6a-b31d-87d08aa072bb
&d[campaignName]=This%20Is%20A%20Campaign%20Name
&d[adId]=dd5b098d-f628-4076-9b2a-7020e8fe1f57
&d[adName]=Podcast%20A%20Ad%20Version%201
&d[seriesName]=Example%Series
&d[episodeName]=Example%20Episode
&ua=Mozilla/5.0%20(Macintosh;%20Intel%20Mac%20OS%20X%20x.y;%20rv:42.0)%20Gecko/20100101%20Firefox/42.0
&uip=89.21.235.86
&cachebuster=4ebac87306df

TIP

If you cannot perform the setup steps directly (some listening apps or platforms will have an account manager set this up), ask or send a link to this section to your account manager in the platform that you are purchasing or setting up advertising in to ask them to setup the Backtracks pixel/tag for your ads.

# Supported Pixel/Tag Parameters

The image pixel/tag or serverside API pixel/tag methods of tracking support the following parameters (typically sent as querystring parameters).

Parameter Name Description Required
k Backtracks Tracking or Project Key Yes
e Event name, set to "impression" (without quotes) Yes
d[campagnId] Campaign identifier Optional
d[campaignName] Campaign name Optional
d[adId] Ad identifier Optional
d[adName] Ad name or description, i.e. Ad In Podcast A Optional
d[seriesId] Id that represents the series identifier Optional
d[seriesName] Name or title of the series or show Optional
d[episodeId] Id that represents the episode identifier Optional
d[episodeName] Name or title of the episode Optional
ua User-Agent (override) Optional
uip User IP address (override) Optional
cachebuster Cachebuster string that is sometimes used to prevent client caching on GET requests Optional

# Content Security Policy

If your website has implemented a Content Security Policy, allow JavaScript to load from https://c.backtracks.fm and/or *.backtracks.fm.