Transaction events (Sales Insights)

  • iOS
  • watchOS
  • tvOS
 

Foreword

This tagging documentation only applies to Tracker from version 2.15.0.

If you can’t see the “Sales Insights” menu entry in Explorer, please get in touch with us so we can activate this for you.

 

Transaction events

With the tracker, an ecommerce instance is available, exposing different objects and methods useful for measuring transaction confirmation.

Additionally, it’s possible to enable automatic tagging of SalesTracker orders by overriding the “autoSalesTracker” configuration variable:

let tracker: Tracker = ATInternet.sharedInstance.defaultTracker
tracker.ecommerce.setAutoSalesTrackerEnabled(true, sync: true, completionHandler: nil)
Tracker* tracker = [ATInternet sharedInstance].defaultTracker;
[tracker.ecommerce setAutoSalesTrackerEnabled:YES sync:YES completionHandler:nil];

The Sales Insights collection domain must be indicated via the “collectDomain” configuration variable:

tracker.ecommerce.setCollectDomain("collect-euw1", sync: true, completionHandler: nil)
[tracker.ecommerce setCollectDomain:@"collect-euw1" sync:YES completionHandler:nil];

See the full list of Ecommerce configuration variables that can be overridden at the bottom of this page.

 

Transaction confirmation

Measuring transaction confirmations is done by creating a TransactionConfirmation object, to which the following can be associated:

  • An ECommerceCart-type cart
  • Shipping data in an ECommerceShipping-type object
  • Payment data in an ECommercePayment-type object
  • Transaction data in an ECommerceTransaction-type object
  • A list of products, products, which can contain one or several ECommerceProduct-type products.

A cart’s properties should be declared as a Dictionary-type collection, with different keys:

  • “id” – String: Cart ID.
  • “currency” – String: Currency.
  • “turnovertaxincluded” – Float: Total amount of cart, including tax (shipping costs included).
  • “turnovertaxfree” – Float: Total amount of cart, excluding tax (shipping costs included).
  • “creation_utc” – Date: Date of creation of the cart (timestamp UTC in seconds).
  • “quantity” – Number: Total number of products in the cart.
  • “nbdistinctproduct” – Number: Number of distinct products in the cart.

A transaction’s properties should be declared as a Dictionary-type collection, with different keys:

  • “id” – String: Transaction ID (mandatory).
  • “promocode” – Array: Promotional code table including one or several codes. A promotional code is declared as a label.
  • “firstpurchase” – Boolean: First customer purchase (0 for no; 1 for yes).

Delivery data should be declared as a Dictionary-type collection, with different keys:

  • “delivery” – String: Name of shipping company.
  • “costtaxincluded” – Float: Amount of shipping costs, including tax.
  • “costtaxfree” – Float: Amount of shipping costs, excluding tax.

Payment method should be declared in a property:

  • “mode” – String: Payment method.

A product’s properties should be declared in a Dictionary-type collection, with different keys:

  • “id” – String: Product ID (mandatory).
  • “variant” – String: Product variant (size, colour, etc.).
  • “$” – String: Product name.
  • “brand” – String: Product brand.
  • “discount” – Boolean: Discounted product (0 for no; 1 for yes).
  • “pricetaxincluded” – Float: Price, including tax.
  • “pricetaxfree” – Float: Price, excluding tax.
  • “currency” – String: Currency.
  • “stock” – Boolean: Product in stock (0 for no; 1 for yes).
  • “quantity” – Number: Number of products in the cart.
  • “category1” – String: The product’s level 1 category (up to 6 tree structure levels are possible; from “category1” to “category6”).

If you use double tagging with SalesTracker, you will need to add a screen as a parameter on initializing the transaction. The page should also be declared as a main goal.

Exemple

let tracker: Tracker = ATInternet.sharedInstance.defaultTracker
// With SalesTracker
tracker.ecommerce.setAutoSalesTrackerEnabled(true, sync: true, completionHandler: nil)
let tc: TransactionConfirmation = tracker.ecommerce.transactionConfirmations.add(screenLabel: "transaction")
// Without SalesTracker
//tracker.ecommerce.setAutoSalesTrackerEnabled(false, sync: true, completionHandler: nil)
//let tc: TransactionConfirmation = tracker.ecommerce.transactionConfirmations.add(screenLabel: nil)
_ = tc.cart.setAll(obj:
    [
        "id": "34",
        "creation_utc": 1514973161, //UTC timestamp in seconds
        "turnovertaxfree": 447.76, //Shipping fees included + discount 8€44
        "turnovertaxincluded": 547.4, //Shipping fees included + discount 10€
        "nbdistinctproduct": 1,
        "quantity": 1,
        "currency": "EUR"
    ]
)
_ = tc.transaction.setAll(obj:
    [
        "id": "27",
        "promocode": ["DQQYRZSJ", "UN1ENE27"],
        "firstpurchase": 0
    ]
)
_ = tc.shipping.setAll(obj:
    [
        "costtaxfree": 7,
        "costtaxincluded": 8.4,
        "delivery": "My carrier"
    ]
)
_ = tc.payment.set(key: "mode", value: "Credit card")
_ = tc.products.append(ECommerceProduct(obj:
    [
        "id": "1",
        "variant": "1",
        "$": "laptop_A56",
        "brand": "ACER",
        "discount": 1,
        "pricetaxincluded": 549,
        "pricetaxfree": 456.2,
        "currency": "EUR",
        "stock": 1,
        "quantity": 1,
        "category1": "Computers_and_Networking",
        "category2": "Computers",
        "category3": "Laptops"
    ]
))
tracker.dispatch()

You may use the independent method “tracker.events.send()” in order to send only your Ecommerce data.

Tracker* tracker = [ATInternet sharedInstance].defaultTracker;
// With SalesTracker
[tracker.ecommerce setAutoSalesTrackerEnabled:YES sync:YES completionHandler:nil];
TransactionConfirmation *tc = [[tracker.ecommerce transactionConfirmations] addWithScreenLabel:@"transaction"];
// Without SalesTracker
//[tracker.ecommerce setAutoSalesTrackerEnabled:NO sync:YES completionHandler:nil];
//TransactionConfirmation *tc = [[tracker.ecommerce transactionConfirmations] addWithScreenLabel:nil];
NSMutableArray *tcproducts = [tc.products mutableCopy];
(void)[tc.cart setAllWithObj:@{
    @"id": @"34",
    @"creation_utc": @1514973161, //UTC timestamp in seconds
    @"turnovertaxfree": @447.76, //Shipping fees included + discount 8€44
    @"turnovertaxincluded": @547.4, //Shipping fees included + discount 10€
    @"nbdistinctproduct": @1,
    @"quantity": @1,
    @"currency": @"EUR"
}];
(void)[tc.transaction setAllWithObj:@{
    @"id": @"27",
    @"promocode": @[@"DQQYRZSJ", @"UN1ENE27"],
    @"firstpurchase": @0
}];
(void)[tc.shipping setAllWithObj:@{
    @"costtaxfree": @7,
    @"costtaxincluded": @8.4,
    @"delivery": @"My carrier"
}];
(void)[tc.payment setWithKey:@"mode" value: @"Credit card"];
[tcproducts addObject:[[ECommerceProduct alloc] initWithObj:@{
    @"id": @"1",
    @"variant": @"1",
    @"$": @"laptop_A56",
    @"brand": @"ACER",
    @"discount": @1,
    @"pricetaxincluded": @549,
    @"pricetaxfree":@ 456.2,
    @"currency": @"EUR",
    @"stock": @1,
    @"quantity": @1,
    @"category1": @"Computers_and_Networking",
    @"category2": @"Computers",
    @"category3": @"Laptops"
}]];
[tc setProducts: tcproducts];
[tracker dispatch];

You may use the independent method “[tracker.events send];” in order to send only your Ecommerce data.

 

Transaction confirmation on server-side

You can validate a cart awaiting payment event by generating a HTTP GET call on server-side:

https://collect-euw1.ati-host.net/hit.xiti?s=XXXXX&col=2&events=[{"name":"transaction.confirmation","data":{"cart_id":"XXXXX", "transaction_id":"XXXXX", "offsite_confirmation":true}]&rdt=off

In this call, you must replace values XXXXX by :

  • the site number concerned by the transaction:
    ?s=XXXXX
  • the cart ID to be validated:
    "cart_id":"XXXXX"
  • the transaction ID:
    "transaction_id":"XXXXX"
 

Appendix

 

Configuration variables

NameDefault valueDescriptionVersion
collectDomain“”Sales Insights collection domain >= 2.12.0
autoSalesTrackerfalseEnable automatic measurement of SalesTracker order content upon a transaction confirmation event >= 2.12.0
 

Was this post helpful?

Last update: 10/09/2019