Pixel Installation

Install the Adverfly tracking pixel on your website

The Adverfly Pixel is a JavaScript snippet that tracks user interactions on your website. It captures pageviews, events, and conversions to power your analytics.

Quick Start

Add the following code to the <head> section of your website:

Request

<script>
  window.adverfly = window.adverfly || [];
  function advPxl() {
    var args = [false];
    for (var i = 0; i < arguments.length; i++) {
      args.push(arguments[i]);
    }
    adverfly.push(args);
  }
  advPxl("init", YOUR_WORKSPACE_ID);
  window.adverfly.store_currency = "EUR";
  window.adverfly.store_timezone = "Europe/Berlin";

  var script = document.createElement("script");
  script.type = "text/javascript";
  script.async = true;
  script.src = "https://sos-de-fra-1.exo.io/adv/advv2.01.js";
  document.getElementsByTagName("head")[0].appendChild(script);
</script>

Replace YOUR_WORKSPACE_ID with your Workspace ID from the Adverfly dashboard.

Configuration

Parameter	Type	Required	Description
`workspace_id`	number	Required	Your Adverfly Workspace ID
`store_currency`	string	Required	Your store's base currency (e.g., EUR, USD)
`store_timezone`	string	Required	Your store's timezone (e.g., Europe/Berlin)

Currency Conversion

The store_currency setting is important for accurate revenue tracking. If a transaction comes in with a different currency (e.g., a customer pays in USD), Adverfly automatically converts it to your store currency using the current exchange rate.

Example: Your store currency is EUR. A customer pays $129 USD. Adverfly converts this to ~€119 EUR in your reports.

Timezone

The store_timezone ensures all events and conversions are recorded in your local time, making your reports easier to read and analyze.

Tracking Events

Track custom events with the Adverfly Pixel

Once the pixel is installed, you can track custom events to capture user interactions.

Basic Event Tracking

Use the advPxl function to track events:

Request

// Add to Cart
advPxl("event", "add_to_cart");

// Initiated Checkout
advPxl("event", "initiated_checkout");

Standard Events

Code	Description
`pageview`	User views a page (tracked automatically on init)
`add_to_cart`	User adds item to cart
`initiated_checkout`	User starts checkout process

Tracking Conversions

Track purchase and lead conversions

Conversions are the most important events to track. They represent completed goals like purchases or lead submissions.

Purchase Conversion

Track when a user completes a purchase:

Request

advPxl("conversion", "purchase", {
  transaction_id: "order123",              // required
  transaction_gross_revenue: 10999,        // required (in cents)
  transaction_currency: "EUR",             // required
  transaction_shipping_costs: 499,         // optional (in cents)
  transaction_tax: 1900,                   // optional (in cents)
  transaction_city: "Berlin",              // optional
  transaction_country_code: "DE",          // optional
  transaction_discount_code: "SUMMER20",   // optional
  customer_id: "customer@email.com",       // optional
  is_new_customer: 1,                       // optional (1 = new, 0 = returning)
});

Conversion Parameters

Parameter	Type	Required	Description
`transaction_id`	string	Required	Unique order ID
`transaction_gross_revenue`	number	Required	Total revenue in cents (e.g., 10999 = €109.99)
`transaction_currency`	string	Required	Currency code (EUR, USD, etc.)
`transaction_shipping_costs`	number	Optional	Shipping costs in cents
`transaction_tax`	number	Optional	Tax amount in cents
`transaction_city`	string	Optional	Customer's city
`transaction_country_code`	string	Optional	ISO country code (DE, US, etc.)
`transaction_discount_code`	string	Optional	Applied discount/coupon code
`customer_id`	string	Optional	Customer identifier (e.g., email)
`is_new_customer`	number	Optional	1 = new customer, 0 = returning

With Line Items

You can also pass individual line items:

Request

advPxl("conversion", "purchase", {
  transaction_id: "order123",
  transaction_gross_revenue: 2000,
  transaction_currency: "EUR",
  transaction_shipping_costs: 350,
  transaction_tax: 150,
  transaction_city: "Berlin",
  transaction_country_code: "DE",
  customer_id: "customer@email.com",
  is_new_customer: 1,
  transaction_items: [
    {
      transaction_item_id: "123",
      transaction_item_name: "Product 1",
      transaction_item_price: 1000,
      transaction_item_tax: 50,
      transaction_item_quantity: 2,
    },
    {
      transaction_item_id: "124",
      transaction_item_name: "Product 2",
      transaction_item_price: 500,
      transaction_item_quantity: 1,
    },
  ],
});

Item Parameters

Parameter	Type	Required	Description
`transaction_item_id`	string	Required	Product/SKU ID
`transaction_item_name`	string	Required	Product name
`transaction_item_price`	number	Required	Item price in cents
`transaction_item_quantity`	number	Required	Quantity purchased
`transaction_item_tax`	number	Optional	Item tax in cents

Lead Conversion

Track when a user submits a lead form:

Request

advPxl("conversion", "lead", {
  transaction_id: "lead-456",
});

Google Tag Manager

Install Adverfly via Google Tag Manager

You can install the Adverfly Pixel using Google Tag Manager for easier management.

Installation Steps

Open your GTM container
Create a new Tag
Choose Custom HTML
Paste the following code:

Request

<script>
  window.adverfly = window.adverfly || [];
  function advPxl() {
    var args = [false];
    for (var i = 0; i < arguments.length; i++) {
      args.push(arguments[i]);
    }
    adverfly.push(args);
  }
  advPxl("init", YOUR_WORKSPACE_ID);
  window.adverfly.store_currency = "EUR";
  window.adverfly.store_timezone = "Europe/Berlin";

  var script = document.createElement("script");
  script.type = "text/javascript";
  script.async = true;
  script.src = "https://sos-de-fra-1.exo.io/adv/advv2.01.js";
  document.getElementsByTagName("head")[0].appendChild(script);
</script>

Set the trigger to All Pages
Save and publish

Configuration

Code	Description
`store_currency`	Your store's base currency. Transactions in other currencies are auto-converted.
`store_timezone`	Your store's timezone for accurate event timestamps in reports.

Tracking Conversions via Data Layer

If you're using the Data Layer for e-commerce events:

Request

<script>
  // This tag should fire on the purchase confirmation page
  advPxl("conversion", "purchase", {
    transaction_id: {{DL - Transaction ID}},
    transaction_gross_revenue: {{DL - Revenue}} * 100,
    transaction_currency: {{DL - Currency}}
  });
</script>

Tracking Custom Events

Create additional tags for custom events:

Request

<script>
  // Add to Cart tag - trigger on add_to_cart event
  advPxl("event", "add_to_cart");
</script>

Request

<script>
  // Initiated Checkout tag - trigger on checkout start
  advPxl("event", "initiated_checkout");
</script>

Recommended Triggers

Code	Description
`Base Pixel`	All Pages
`Purchase Conversion`	purchase event / thank you page
`Add to Cart`	add_to_cart event
`Initiated Checkout`	initiated_checkout event

Shopify Integration

Install Adverfly on your Shopify store

Adverfly integrates natively with Shopify's Customer Events API for accurate tracking.

Installation Steps

Go to your Shopify Admin
Navigate to Settings → Customer events
Click Add custom pixel
Name it "Adverfly"
Paste the following code:

Request

const script = document.createElement("script");
script.type = "text/javascript";
script.async = true;
script.src = "https://sos-de-fra-1.exo.io/adv/script-shopify.js";
document.getElementsByTagName("script")[0].parentNode.appendChild(script);

window.adverfly_web_pixel = true;
window.adverfly_init = init;
window.adverfly_browser = browser;
window.adverfly_settings = api.settings;

window.adverfly = window.adverfly || [];
window.advPxl = function () {
  adverfly.push([false, ...arguments]);
};

analytics.subscribe("all_events", (event) => {
  window.adverfly.push(["all_shopify_events", event]);
  advPxl("init", YOUR_WORKSPACE_ID);
  window.adverfly.store_currency = "EUR";
  window.adverfly.store_timezone = "Europe/Berlin";

  if (event.name === "page_viewed") {
    advPxl("check", "vikeys", event);
  }
});

Replace YOUR_WORKSPACE_ID with your Workspace ID and set your store's currency and timezone.

Configuration

Code	Description
`store_currency`	Your store's base currency. Transactions in other currencies are auto-converted.
`store_timezone`	Your store's timezone for accurate event timestamps in reports.

Tracked Events

The Shopify integration automatically tracks all standard e-commerce events:

Code	Description
`page_viewed → pageview`	Shopify page_viewed event, recorded as pageview in Adverfly
`product_added_to_cart → add_to_cart`	Shopify add to cart event, recorded as add_to_cart in Adverfly
`checkout_started → initiated_checkout`	Shopify checkout start, recorded as initiated_checkout in Adverfly
`checkout_completed → purchase`	Shopify purchase event, recorded as purchase conversion in Adverfly

Surveys

Embed Adverfly surveys on your website

Embed Adverfly surveys directly on your website to collect customer feedback, post-purchase reviews, or NPS scores.

Quick Start

If you already have the Adverfly pixel installed, simply add this div where you want the survey to appear:

Request

<div data-adv-survey-id="SURVEY_ID" data-adv-workspace-id="WORKSPACE_ID"></div>

Replace SURVEY_ID with your survey ID and WORKSPACE_ID with your workspace ID (both found in the survey settings).

The pixel automatically detects survey embeds and renders them.

Parameters

Parameter	Type	Required	Description
`data-adv-survey-id`	string	Required	Your survey ID
`data-adv-workspace-id`	string	Required	Your workspace ID
`data-adv-survey-version`	string	Optional	Specific survey version (uses latest by default)
`data-adv-order-id`	string	Optional	Order/transaction ID to link survey responses to a specific purchase
`data-adv-lang`	string	Optional	Language code like de, fr, en, or default. Omitting it keeps the legacy English UI fallback.

Customer & Transaction Tracking

Survey events automatically include customer_id and transaction_id when set via the Adverfly Layer. This allows you to link survey responses to specific customers and orders.

Request

<script>
  window.adverfly = window.adverfly || [];
  function advPxl() { adverfly.push([!1, ...arguments]); }
  advPxl("init", WORKSPACE_ID);
  window.adverfly.store_currency = "EUR";
  window.adverfly.store_timezone = "Europe/Berlin";

  /* Set customer and transaction IDs */
  window.adverfly.customer_id = "customer_123";
  window.adverfly.transaction_id = "order_456";
</script>

Adverfly Layer Properties

Parameter	Type	Required	Description
`window.adverfly.customer_id`	string	Optional	Customer ID to associate with survey responses
`window.adverfly.transaction_id`	string	Optional	Transaction/Order ID to link survey responses to purchases
`window.adverfly.store_currency`	string	Optional	Store currency (e.g., EUR, USD)
`window.adverfly.store_timezone`	string	Optional	Store timezone (e.g., Europe/Berlin)

These properties are automatically included in all survey events (survey_opened, survey_answer, survey_completed).

Multi-Language Support

Surveys support multiple languages. Set data-adv-lang to display translated content. Use default to force the survey base content while keeping the UI fallback in English:

Request

<div
  data-adv-survey-id="SURVEY_ID"
  data-adv-workspace-id="WORKSPACE_ID"
  data-adv-lang="de"
></div>

Code	Description
`default`	Base survey content with English UI fallback
`en`	English UI, and translations.en if configured
`de`	German
`fr`	French (if configured)

If data-adv-lang is omitted entirely, the public embed keeps the legacy behavior: English UI with the survey base content. Translations must be configured in the survey settings within Adverfly.

Survey Features

Required questions: Questions marked as required show a red asterisk (*) and validate before proceeding
Multi-step navigation: Surveys display one question at a time with Back/Next buttons
Progress indicator: Shows current step and progress bar
Thank you screen: Customizable message after submission

Survey Requirements

For the embed to work, your survey must:

Be set to live status
Have the Adverfly v2 pixel installed on the page (surveys are not supported in the v1 pixel)

Survey Events

The pixel automatically tracks these events for analytics:

Code	Description
`survey_opened`	Fired when survey is displayed to user
`survey_answer`	Fired for each question answered
`survey_completed`	Fired when user submits the survey

All events include form_id, submission_id, and (if set) customer_id and transaction_id.