Client-side events JS library

Getting Started

Each step is outlined in detail below

Our client-side events library allows you to send customer events to Tracify from the browser.

Install the Tracify tracking snippet on all pages that you wish to track
- Install development environment snippet for testing purposes (optional).
- Install production environment snippet for live data. (required)
Configure individual tracking events.
- During this step you'll determine which events (actions) you would like to track (e.g. purchase events).
- Speak with your Account Manager to determine which events are appropriate for your business.
Verify events are sent in your developer console.
Confirm with your Account Manager that events are being recorded.

Installation: Development Environment

If you wish to send test events to check your integration you will need to use the development environment. This is an optional step.

Replace the csid in the selected script below with your actual csid provided by Tracify and paste within the <head></head> tags of your website on all pages. Speak with your Account Manager to verify your integration is working proprely without sending test data to your main reports.

3rd Party Tracking

<script type="text/javascript" src="https://devscripting.tracify.ai/api.v1.js"></script>
<script type="text/javascript">
  var tracify = Tracify({ csid: "00000000-0000-000-0000-000000000000", fingerPrint: true });
  tracify.capturePageView();
</script>

1st Party Tracking

If you've configured your account to use first party tracking and wish to send test events you will need to change the src="" link to src="https://devscripting.yourdomain.ai/api.v1.js" where yourdomain.com is the domain of your account property.

<script type="text/javascript" src="https://devscripting.yourdomain.com/api.v1.js"></script>
<script type="text/javascript">
  var tracify = Tracify({ csid: "00000000-0000-000-0000-000000000000", fingerPrint: true });
  tracify.capturePageView();
</script>

Installation: Production Environment

When you are ready to send live data to Tracify you will need to use the production environment. Replace the csid in the script below with your actual csid provided by Tracify and paste within the <head></head> tags of your website on all pages.

3rd Party Tracking

<script type="text/javascript" src="https://scripting.tracify.ai/api.v1.js"></script>
<script type="text/javascript">
  var tracify = Tracify({ csid: "00000000-0000-000-0000-000000000000", fingerPrint: true });
  tracify.capturePageView();
</script>

1st Party Tracking

If you've configured your account to use first party tracking and wish to send test events you will need to change the src="" link to src="https://script.yourdomain.ai/api.v1.js" where yourdomain.com is the domain of your account property.

<script type="text/javascript" src="https://script.yourdomain.com/api.v1.js"></script>
<script type="text/javascript">
  var tracify = Tracify({ csid: "00000000-0000-000-0000-000000000000", fingerPrint: true });
  tracify.capturePageView();
</script>

Fingerprinting

Client-side fingerprinting results in better tracking accuracy. In our above examples it is turned on, but you may disable it by modifying your installation script and removing fingerPrint: true

<script type="text/javascript" src="https://scripting.tracify.ai/api.v1.js"></script>
<script type="text/javascript">
  var tracify = Tracify({ csid: "00000000-0000-000-0000-000000000000"});
  tracify.capturePageView();
</script>

Set up Events

The installation snippets above will only track page views. To track other events, like purchases, you will need to call the necessary event function when a user takes an action. You can add events anywhere in your javascript below the main installation script.

Recommended E-Commerce Events

Product View: Track each time a customer views a product page.
Add to Cart: Track each time a customer adds an item to their cart.
Purchase: Track each time a customer makes a purchase.

Recommended Leadgen Events

Conversion Event: Track when a customer completes your conversion action (email signup / download, etc.)

Example Code

In the following example the main snippet is installed in the <head></head> section. A second purchase event is installed in the <body></body>. This is a simple example of what sending a purchase event from a confirmation page might look like. Note the highlighted rows.

<!DOCTYPE html>
<html>
    <head>
        <title>Thank you for your order!</title>

        <!-- Initializes script / sends pageview event -->
        <script type="text/javascript" src="https://scripting.tracify.ai/api.v1.js"></script>
        <script type="text/javascript">
          var tracify = Tracify({ csid: "00000000-0000-000-0000-000000000000", fingerPrint: true });
          tracify.capturePageView();
        </script>

    </head>
    <body>
        <h1>Hello, World!</h1>
        <p>Thank you for your purchase! We appreciate your business</p>

        <!-- Calls a purchase order. Note the values passed for amound, orderId, etc. -->
        <script type="text/javascript">
          tracify.capturePurchase({
          amount: "21.11",
          orderId: "12345",
          currency: "EUR",
          email: "customer@yourwebsite.com",
          dateTime: new Date()
          });
        </script>

    </body>
</html>

Supported Events

Product View Event (Ecom)

Track when a customer views a product page. Generally triggered on product description pages (PDP).

tracify.captureProductView();

Add to Cart Event (Ecom)

Track when a customer adds items to their cart.

tracify.captureAddToCart();

Purchase Event (Ecom)

Track when a customer completes a purchase. This event is used by Tracify to track your return on ad spend (ROAS)

Required Parameters:

amount: The amount of the purchase.
orderId: The order ID associated with the purchase. Must be unique for purposes of depuplication
currency: The currency used to make the purchase. Please use the appropriate 3-letter ISO-4217 code.

Optional Paramaters:

email: The email address of the customer. Sending an email in the tracking event improves accuracy. Emails are automatically anonymized to protect privacy.
dateTime: dateTime must be an instance of the Date object and is an optional field. If you do not provide it, the current date and time will be used.
storeUnhashedOrderId: False by default if not set. If you set this flag to True, the event processing will store the unhashed order ID in the event table. Only use this option if your order ID is not personal information or if you have explicit consent. The person providing the data and setting this flag is responsible for obeying these rules! Tracify GmbH, its employees, or its partners cannot be held accountable for failing to follow these rules and storing privacy-related information in our database tables.

Example Call

tracify.capturePurchase({
  amount: "21.11", orderId: "12345", currency: "EUR", email: "customer@yourwebsite.com", dateTime: new Date()
});

General Conversion Event (Leadgen)

Track conversions other than purchases (leads, downloads). Trigger this event when a customer completes your desired action. Tracify currently supports one conversion event per customer journey, meaning that you cannot trigger a general conversion followed by a purchase conversion.

Required Parameters:

value: Used to calculate your ROI on advertising spend. Set it to a value that matches the type of conversion you are tracking (lead value, download value etc.). This value may be 0.
conversionId: is a unique identifier which Tracify uses to make sure the same conversion is only counted once. We recommend to use something unique like a customer's email here. By default conversion IDs are anonymized to protect privacy.
currency: The currency you use to calculate ROI. Please use the appropriate 3-letter ISO-4217 code.

Optional Paramaters:

email: The email address of the customer. Sending the email in the tracking event improves accuracy. Emails are automatically anonymized to protect privacy.
dateTime: dateTime must be an instance of the Date object and is an optional field. If you do not provide it, the current date and time will be used.
storeUnhashedConversionId: False by default if not set. If you set this flag to True, the event processing will store the unhashed conversion ID in the event table. Only use this option if your conversion ID is not personal information or if you have explicit consent. The person providing the data and setting this flag is responsible for obeying these rules! Tracify GmbH, its employees, or its partners cannot be held accountable for failing to follow these rules and storing privacy-related information in our database tables.

Example Call

Example leadgen conversion where the email of the lead is captured:

tracify.captureConversion({
  value: "24.11", conversionId: "customer@yourwebsite.com", currency: "EUR", email: "customer@yourwebsite.com", dateTime: new Date()
});

Verifying Events

The easiest way to determine if events are sending properly is open Developer Tools in your browser and visit the Network tab. Make sure that your browser is set to record network activity, and load the page you are troubleshooting. Once the page has loaded, search for the event in question e.g. pageview. You should see a network request for the event along with a status code of 200 OK in the request headers. If you do not see the event, or if the event resolves in an error check your implementation to see if there are any mistakes.

Network activity with 200 OK status code

Troubleshooting

Common Problems

The incorrect CSID is referenced in the main javascript snippet - see our Installation section.
The function to fire the event is not called - see our Set up Events section.

Landing Page Tools

Occasionally you may encounter errors where Tracify's script fails to execute due to an Uncaught ReferenceError: Tracify is not defined error with certain landing page tools. This occurs because the page loads the script out of order.

To handle this issue update your code to force event calls to wait for initialization:

<script src="https://scripting.tracify.ai/api.v1.js" onload="initializeTracify()"></script>
<script type="text/javascript">
    function initializeTracify() {
        if (typeof Tracify === 'function') { 
            var tracify = Tracify({ csid: "00000000-0000-000-0000-000000000000", fingerPrint: true });

            // Add tracking events below this line
            //  e.g tracify.capturePageView();

        } else {
            console.error('Tracify is not loaded properly.');
        }
    }
</script>

This applies to the following landinge page tools:

Perspective