Backtracks for Developers

# Getting Started

# Install JavaScript

Add the following JavaScript to your webpages or website.

<script>
(function(b,a,c,k,t,r,s,f){b['BacktracksAttributionName']=r;b[r]=b[r]||function(){
(b[r].q=b[r].q||[]).push(arguments)},b[r].l=1*new Date();s=a.createElement(c),
f=a.getElementsByTagName(c)[0];s.async=1;s.src=k;f.parentNode.insertBefore(s,f);
b['BacktracksAttributionConfig']=t;b[r]('pageview');
})(window,document,'script','https://c.backtracks.fm/bt-attribution.min.js', 
{key: 'YOUR BT KEY'},'bta');
</script>

The script tag in the above is an optimized code snippet that is installed or added to webpages where you wish to track revenue, conversions, and actions resulting from advertising.

The script can run multiple times on one page; it will never load the manager script more than once. It's not necessary to add the load script more than once per page, but if you accidentally do, there will be no issues. The script tag is added to your webpage, website, theme, or e-commerce site.

# Record Events

Recording events that users take encriches the accuracy of data available for attribution reporting. As users perform actions like purchasing items, adding items to a cart, viewing items, signing up, etc. you will want to record that information to allow it to be tied to the metrics for the effectiveness of advertising, promotions, placements, or campaigns.

Recording different types of events is performed by integrating Backtracks Attribution with your webpage, website, or e-commerce portal.

// Example
bta('purchase', {
    userId: "b60803ce-fcc7-4c03-a2dc-ee8850f81c60",
    sessionId: "32a00408-4224-498b-ab76-fe8f734a11fb",
    adId: "4fc96be7-f54e-4b91-a17a-f8b4b7215bf8",
    adName: "Ad Name",
    adGroupId: "3911af96-8ea7-482a-bc76-8189cc7452ca",
    adGroupName: "Ad Group Name",
    campaignId: "XyZ132aabbCdEf",
    campaignName: "Campaign Name",
    conversionDateTime: "2020-10-18T14:25:09.543Z",
    orgId: "XyZ132aabbCdEf",
    orgName: "Org Name",
    transactionId: "67ebba62-5534-4048-b74a-9e6ff15bd90a",
    discountCode: "abc-123",
    locale: "en-GB",
    currency: "USD",
    storefrontId: "09b6006d-56f9-450b-93ac-2b82e297893e",
    storefrontName: "Storefront Name",
    tax: 1.24,
    shipping: 1.24,
    value: 31.44,
    items: [{
            id: "abc-123",
            sku: "xyz-11111111",
            name: "Something Product",
            brand: "Something Company",
            category: "Apparel/Shoes",
            quantity: 2,
            variant: "Yellow",
            price: 10
        },
        {
            id: "222-333",
            sku: "2abc-222222222",
            name: "Another Product",
            brand: "Another Company",
            category: "Apparel/Shirts",
            quantity: 2,
            variant: "Green",
            price: 5
        }
    ],
});

# Events

# purchase

Record a purchase

bta('purchase', {
    userId: "{{ user.id }}",
    adId: "{{ ad.id }}",
    adName: "{{ ad.name }}",
    adGroupId: "{{ adGroup.id }}",
    adGroupName: "{{ adGroup.name }}",
    campaignId: "{{ campaign.id }}",
    campaignName: "{{ campaign.name }}",
    transactionId: "{{ order.id}}",
    discountCode: "{{ order.discountCode }}",
    locale: "en-US",
    currency: "USD",
    storefrontId: "{{ storefront.id }}",
    storefrontName: "{{ storefront.name }}",
    tax: 1.24,
    shipping: 1.24,
    value: 31.44,
    items: [{
            id: "{{ product.id }}",
            sku: "{{ product.sku }}",
            name: "{{ product.title }}",
            brand: "{{ product.vendor }}",
            category: "{{ product.type }}",
            quantity: 2,
            variant: "{{ variant.title }}",
            price: {{ product.price }}
        },
        {
            id: "{{ product.id }}",
            sku: "{{ product.sku }}",
            name: "{{ product.title }}",
            brand: "{{ product.vendor }}",
            category: "{{ product.type }}",
            quantity: 2,
            variant: "{{ variant.title }}",
            price: {{ product.price }}
        }
    ],
});
# addtocart

Record adding one or more items to a cart

bta('addtocart', {
    currency: "USD",
    value: {{ product.price }},
    items: [{
            id: "{{ product.id }}",
            sku: "{{ product.sku }}",
            name: "{{ product.title }}",
            brand: "{{ product.vendor }}",
            category: "{{ product.type }}",
            variant: "{{ variant.title }}",
            quantity: 2,
            price: {{ product.price }}
    }]
});
# lead

Record a lead or signup, i.e. user filled out a form

bta('lead', {
  currency: "USD",
  value: 31.44 // what is the value of the lead
});
# pageview

Record a pageview, i.e. user visited a webpage

bta('pageview');
# viewitem

Record viewing an item or product

bta('viewitem', {
    currency: "USD",
    value: {{ product.price }},
    items: [{
            id: "{{ product.id }}",
            sku: "{{ product.sku }}",
            name: "{{ product.title }}",
            brand: "{{ product.vendor }}",
            category: "{{ product.type }}",
            variant: "{{ variant.title }}",
            price: {{ product.price }}
    }]
});
# download

Record a download of an item or product

bta('download', {
    currency: "USD",
    value: {{ product.price }},
    items: [{
            id: "{{ product.id }}",
            sku: "{{ product.sku }}",
            name: "{{ product.title }}",
            brand: "{{ product.vendor }}",
            category: "{{ product.type }}",
            variant: "{{ variant.title }}",
            price: {{ product.price }}
    }]
});

Click the icon to expand the code sample below.

# Properties

TIP

All event properties are optional. Capture as much or as little data as you want or need, but in general recording data if it is available is recommended for enhanced metrics and reporting.

# Action/Event Properties

Property Type Description
adGroupName string Name of the ad group associated with the recorded action
adId string Unique identifier of the advertisement
adName string Name of an/the ad associated with the recorded action
campaignId string Campaign identifier for the advertising or marketing campaign
campaignName string Campaign name for the advertising or marketing campaign
conversionDateTime date/time ISO 8601 formatted date/time in the UTC timezone of when the action occurred if it is not the current date/time
currency string ISO 4217 formatted three-letter curency code that applies to the curreny values, i.e. USD, GBP, EUR, CAD, etc.
discountCode string Discount or promo code
items list of products/items Products or items associated with the action. See the product/items properties for the properties for each item.
locale string Locale or language of the user or storefront
orgId string Organization identifier
orgName string Organization name
sessionId string Unique identifier for the user's browsing session, i.e. all interactions in the current browsing session
shipping decimal Shipping total
storefrontId string Unique identifer for the storefront
storefrontName string Name of the storefront, e.g. "Fred's Sporting Goods"
tax decimal Tax total
transactionId string Unique transaction identifier, i.e. orderId, cartId, etc.
userId string Unique user identifier in the storefront or website
value decimal Total value, i.e. order total, lead value, cart total, etc.

# Product/Item Properties

Each event that is tracked with Backtracks Attribution may optionally track which items or products are associated with the event. Recording which items or products are being purchased, added to a cart, viewed, etc. is data that enables tracking and reporting on effectiveness of that advertisement or campaign for the intended user action in detail, i.e. this ad resulted in the advertised product, brand, etc. being purchased. Recording the item-level data is recommended.

Property Type Description
id string Identifer of the item in the store or site, i.e. item/product id
sku string SKU (Stock Keeping Unit) of the item/product in the store or site
name string Name of the item, "ACME Shirt"
brand string Brand of the item, e.g. "ACME Company"
category string Category of the item, e.g. "Apparel/Shoes"
quantity integer Quantity of the item
variant string Variant of the item, i.e. "Red", "Size 11", etc.
price decimal Price of the item as a numeric decimal, e.g. 10.23

# Integration Quickstarts

The following are integration quickstart guides:

← Advanced →