Web SDK | Product & Technical Documentation

The web SDK enables a number of FunnelConnect services, including:

Info Ident Track API.
ID Sync (for example Floodlight and other AdTech and conversion tracking solutions).
Utiq martechpass.

The web SDK is integrated using fcTag.js.

Teavaro’s media integration services operate only under our client’s domain(s). This is in line with our services acting solely as data processor and any data obtained fully belonging to the client.

A prerequisite for the web SDK integration is therefore the setup of a subdomain for all of the sites its running on, see Creating Subdomain. Please also confirm if you are using subdomains, as we will need to enable them.

Profile data returned with Info Ident Track API calls is stored in fcData local storage key as JSON object.

Getting Started

The Web SDK loads via a first-party subdomain of your website. The subdomain prefix is a 2–4 letter acronym unique to your account.

JavaScript

(function() {
  function load(src, callback) {
    var promise = new Promise(function(resolve) {
      var s = document.createElement('script');
      s.src = src;
      s.async = false;
      s.onload = s.onerror = resolve;
      (document.head || document.documentElement).appendChild(s);
    });
    if (callback) {
      promise.then(callback);
    }
    return promise;
  }
  load('https://{sub-domain}.{domain-name}/{domain-name, dot(s) are hyphenated}.js', function() {
    load('https://{sub-domain}.{domain-name}/fcTag.js');
  });
})();

Integration via Tag Manager

Teavaro supports any tag manager integration, for example using GTM with custom HTML tag:

JavaScript

<script>
(function() {
  function load(src, callback) {
    var promise = new Promise(function(resolve) {
      var s = document.createElement('script');
      s.src = src;
      s.async = false;
      s.onload = s.onerror = resolve;
      (document.head || document.documentElement).appendChild(s);
    });
    if (callback) {
      promise.then(callback);
    }
    return promise;
  }
  load('https://{sub-domain}.{domain-name}/{domain-name, dot(s) are hyphenated}.js', function() {
    load('https://{sub-domain}.{domain-name}/fcTag.js');
  });
})();
</script>

CMP Integration

If you are using a Consent Manager Platform to manage your cookie consent, we recommend that you only load the Teavaro tag once the required consent has been granted.

The Teavaro service can also capture the cookie consent to store it against the user profile.

To ensure privacy compliant tracking, it is essential to explicitly document user consent for tracking purposes. Below is an example code snippet based on OneTrust that can be modified according to your specific needs:

JavaScript

// Replace 'C0004' with your tracking category's Group ID
var trackingGroupId = 'C0004';

OneTrust.OnConsentChanged(function () {
    var trackPermissionValue = OneTrust.GetConsentStatusForGroup(trackingGroupId);
    localStorage.setItem('consentProvided', trackPermissionValue ? 'true' : 'false');
});

The consentProvided key in localStorage should remain unchanged, and its value must be expressed as a boolean, using one of the following formats:

true or false
0 or 1

If the consentProvided key is null / not set, tracking capabilities enabled via the Web SDK will be executed. Consent is assumed granted or not required.

Teavaro Native CMP

Teavaro provides a server-side consent manager, which lets you define any type of data collection and processing purpose and enforce it across all data pipelines. For more details see Teavaro Consent Manager.

To enable Teavaro’s CMP include teavaroConsentManager.js in the tag. The Web SDK and FunnelConnect pipelines will be enabled by Teavaro accordingly as part of the service setup.

Tag Enablement

HTML

<script>
(function() {
  function load(src, callback) {
    var promise = new Promise(function(resolve) {
      var s = document.createElement('script');
      s.src = src;
      s.async = false;
      s.onload = s.onerror = resolve;
      (document.head || document.documentElement).appendChild(s);
    });
    if (callback) {
      promise.then(callback);
    }
    return promise;
  }
  load('https://{sub-domain}.{domain-name}/{domain-name, dot(s) are hyphenated}.js', function() {
    load('https://{sub-domain}.{domain-name}/teavaroConsentManager.js');
    load('https://{sub-domain}.{domain-name}/fcTag.js');
  });
})();
</script>

Notification Template Configuration

The Consent Manager UI can be customized using predefined templates, including configurable text, branding, colors, links, and detailed descriptions of the purposes and technologies used. Each Consent Manager template is defined as a JSON file. The following example illustrates the available configuration entries:

JSON

{
  "website": "brand-demo.com",
  "title": "Cookie Consent",
  "colorTheme": "default",
  "teavaroLogoUrl": "https://www.brand-demo.com/logo.png",

  "titleTechnicalCookies": "Strictly Necessary",
  "titleOnlineMarketing": "Marketing",
  "titleOptimisation": "Performance & Analytics",
  "titleNextBestAction": "Personalization",

  "summaryTechnicalCookiesText": "",
  "summaryOmText": "",
  "summaryOptText": "",
  "summaryNbaText": "",

  "descriptionTechnicalCookiesText": "These cookies are necessary for the operation of the website.",
  "descriptionOmText": "We use cookies to show personalized advertisements.",
  "descriptionOptText": "These cookies help us understand how visitors interact with our website.",
  "descriptionNbaText": "These cookies allow us to provide personalized content and offers.",

  "rejectText": "REJECT ALL",
  "acceptText": "ACCEPT ALL",
  "settingsText": "SAVE MY CHOICES",

  "mainDescription": "This website uses cookies and third-party technologies that require your consent.",

  "impressumUrl": "https://teavaro.com/cookie-policy",
  "impressumText": "Cookie Policy",
  "privacyUrl": "https://teavaro.com/privacy-policy",
  "privacyText": "Privacy Policy",

  "customiseText": "Cookie Settings",
  "poweredByText": "Powered by Teavaro",

  "titleUtiqCookies": "Use of Utiq technology powered by your telecom operator",
  "summaryUtiqCookiesText": "Information about the activation and use of Utiq technology.",
  "descriptionUtiqCookiesText": "Detailed information about Utiq technology and its privacy controls."
}

website

Type: String
Description: Website domain associated with the Consent Manager. This value is used in the default consent title to identify the website requesting consent.
Default: Current website hostname (window.location.hostname).

colorTheme

Type: String
Description: Theme identifier used to assign predefined CSS styles to the Consent Manager. Setting this property adds theme-specific classes and IDs to the rendered elements, allowing customization of colors, typography, layout, and branding.
Default: default (defined in the default consent template).

teavaroLogoUrl

Type: String
Description: URL of the logo displayed in the Consent Manager. Leave empty if no logo should be displayed.
Default: Empty string (defined in the default consent template).

title

Type: String
Description: Main heading displayed in the Consent Manager preferences window. It identifies the website and introduces the consent choices available to the user.
Default: I consent to below choices on [website] and other domains of the group.

titleTechnicalCookies

Type: String (Optional)
Description: Title displayed for the strictly necessary cookies category. This category represents technologies required for essential website functionality and consent management.
Default: Technical title (defined in the default consent template).

titleOnlineMarketing

Type: String
Description: Title displayed for the online marketing consent category. This category covers technologies used for advertising, marketing, and social media integrations.
Default: Marketing and Social Network

titleOptimisation

Type: String
Description: Title displayed for the optimization consent category. This category covers technologies used to analyze website activity and improve performance and user experience.
Default: Analytics Cookies

titleNextBestAction

Type: String
Description: Title displayed for the personalization consent category. This category covers technologies used to recognize users across devices and provide personalized content and offers.
Default: Personal Offers

summaryTechnicalCookiesText

Type: String (Optional)
Description: Short description displayed below the strictly necessary cookies category title. It provides an overview of the essential technologies used by the website.
Default: Technical summary (defined in the default consent template).

summaryOmText

Type: String
Description: Short description displayed below the online marketing category title. It explains how cookies are used to evaluate user behavior, provide relevant offers, and share information with marketing, analytics, and social media partners.
Default: Our cookies evaluate your behavior and present relevant offers. We share this information with trusted analytics, marketing, and social media partners.

summaryOptText

Type: String
Description: Short description displayed below the optimization category title. It explains how cookies help improve the website by analyzing visitor behavior, including visit duration and return frequency.
Default: Enhance your experience. Our cookies improve our website by analyzing visitor behavior, such as page duration and return frequency.

summaryNbaText

Type: String
Description: Short description displayed below the personalization category title. It explains how cookie-based identification can recognize users across devices and provide consistent preferences and personalized offers.
Default: Our cookie-based identification assigns your profile to all recognized devices, ensuring consistent settings and personalized offers.

descriptionTechnicalCookiesText

Type: String (Optional)
Description: Detailed description displayed within the strictly necessary cookies category. It provides additional information about the essential technologies required for website functionality.
HTML formatting can be included to display structured content such as paragraphs, bold text, and lists.
Default: Technical description (defined in the default consent template).

descriptionOmText

Type: String
Description: Detailed description displayed within the online marketing category. It provides additional information about marketing technologies, social media integrations, and how browsing behavior may be associated with user profiles.
HTML formatting can be included to display structured content.
Default: If you're logged in to a social network, your user profile may be enriched with your surfing behavior.

descriptionOptText

Type: String
Description: Detailed description displayed within the optimization category. It provides additional information about website analytics, performance measurement, and information shared with analytics partners.
HTML formatting can be included to display structured content.
Default: We share this information with trusted analytics partners.

descriptionNbaText

Type: String

Description: Detailed description displayed within the personalization category. It provides additional information about user identification, profile recognition, and how collected information may be used to deliver personalized experiences.
HTML formatting can be included to display structured content.
Default: Your surfing behavior is not utilized for this purpose. Registering for our newsletter allows us to identify you and link it to your profile.

acceptText

Type: String
Description: Text displayed on the button that allows users to accept all available consent categories.
Default: Accept All

rejectText

Type: String
Description: Text displayed on the button that allows users to reject optional consent categories.
Default: Reject All

settingsText

Type: String
Description: Text displayed on the button that saves the user’s selected consent preferences.
Default: Save Settings

mainDescription

Type: String
Description: Main informational text displayed in the Consent Manager. It explains the use of cookies and third-party technologies, the purposes of personal data processing, and the user’s ability to manage or withdraw consent.
HTML formatting can be included to provide additional information, links to privacy policies, and descriptions of specific technologies.
Default: This site uses cookies and third-party technologies that require your consent to integrate certain features. If you consent here, these features will be activated. After your consent, we and the relevant third-party companies will process your personal data for various purposes. You can revoke your consent or adjust your cookie settings at any time. Detailed information on the purpose, legal basis, and third-party companies can be found in our privacy policy.

impressumUrl

Type: String
Description: URL of the website’s legal information or imprint page. This value is used as the destination of the corresponding link in the Consent Manager.
Default: #

impressumText

Type: String
Description: Text displayed for the link to the website’s legal information or imprint page.
Default: Impressum

privacyUrl

Type: String
Description: URL of the website’s privacy policy. This value is used as the destination of the corresponding link in the Consent Manager.
Default: #

privacyText

Type: String
Description: Text displayed for the link to the website’s privacy policy.
Default: Privacy Policy

customiseText

Type: String
Description: Text displayed on the interface element that allows users to access or modify their consent preferences.
Default: Customise Preferences

poweredByText

Type: String
Description: Attribution text displayed in the Consent Manager interface.
Default: Powered by Teavaro

titleUtiqCookies

Type: String (Optional)
Description: Title displayed for the Utiq consent category. This category provides information about Utiq technology and its use of pseudonymous identifiers for marketing, analytics, and personalization.
The Utiq consent category is only rendered when UTIQ_CONFIGURATION.enableConsentIntegration is enabled in the FunnelConnect configuration and the required Utiq template content is provided.
Default: None.

summaryUtiqCookiesText

Type: String (Optional)
Description: Short description displayed below the Utiq consent category title. It explains the activation and use of Utiq technology, including supported internet connections and participating telecom operators.
HTML formatting can be included to provide additional information and links to Utiq’s privacy documentation.
Default: None.

descriptionUtiqCookiesText

Type: String (Optional)
Description: Detailed description displayed within the Utiq consent category. It explains how Utiq technology works, how pseudonymous identifiers are generated and used, and how users can manage their privacy preferences.
HTML formatting can be included to provide structured explanations and links to Utiq’s privacy statement and consent management portal.
The Utiq consent category is only rendered when UTIQ_CONFIGURATION.enableConsentIntegration is enabled in the FunnelConnect configuration, and the required Utiq template content is provided.
Default: None.

Notes

Default values

Most text properties have predefined English fallback values provided by getEnContent().

These fallback values are used when the corresponding property is null or undefined.

Default template

The defaultConsentTemplate defines initial values for website, colorTheme, teavaroLogoUrl, and the three technical cookies properties.

These initial values are separate from the English localization fallbacks.

Optional technical cookies category

The technical cookies properties are optional in the TypeScript configuration.

The Consent Manager conditionally creates the technical cookies section based on the presence of its title, summary, and description properties.

Optional Utiq category

The Utiq consent category requires the following configuration:

UTIQ_CONFIGURATION.enableConsentIntegration

It also requires the corresponding title, summary, and description properties to be provided in the template.

HTML content

Description fields and other informational text can contain HTML markup, including paragraphs, hyperlinks, bold text, and lists, as demonstrated by the provided configuration.

Theme Customization

The Consent Manager appearance can be customized using three CSS files:

palette.css: Defines the color palette used throughout the Consent Manager, including background colors, text colors, buttons, and other UI elements.
media.css: Defines responsive styles and media queries to ensure the Consent Manager displays correctly across different screen sizes and devices.
styles.css: Defines the general appearance of the Consent Manager, including typography, spacing, layout, buttons, and other visual elements.

Teavaro can provide a default theme with predefined styles and branding. However, clients are free to modify these CSS files to match their specific design requirements and corporate identity.

The colorTheme configuration property determines which theme-specific CSS classes are applied to the Consent Manager elements, allowing customized styles to be used without modifying the underlying functionality.

Data Layer Data Capture

While Teavaro provides its own fcDataLayer data layer, more commonly clients tap into their existing data layers.

Our Web SDK provides the means to configure what data, including nested JSON objects, are included with analytics tracking.

Google and other Data Layers

Our library can capture data from 3rd party data layers, for example, Google’s dataLayer or Tealium’s utag data layer.

JavaScript

{
  "ROOT_VARIABLE": ["anyDataLayer1", "anyDataLayerN, "anyDataLayer:specificKey"],
  "VARIABLES_DELIMITER": ":",
  "SITE_VARIABLES": ["anyVariable1", "anyVariable2", "anyVariableN"],
  "TRACK_DATALAYER_VARIABLES": {
      anyDataLayer1: {
        anyVariable1: [1, 2],
        anyVariable2: [3],
      },
      // note: for objects wrapped inside arrays, an extra level must be added
      anyDataLayer2: {
        anyVariable1: [2],
      },
    },
  "GOOGLE_CONFIGURATION": {
    "DISPATCH_DATALAYER_UPDATED_EVENT": true,
    "EVENT_ATTRIBUTE_LIST": {
      "event_name" : ["attribute1, attribute2,", "attributeN"]
    },
    "GOOGLE_DATALAYER_NAME": "dataLayer"
  },
  "MATOMO_CONFIGURATION": {
    "PUSH_FUNCTION_CONTAINER": "_mtm",
    "DISPATCH_DATALAYER_UPDATED_EVENT": true,
  },
}

For a comprehensive overview of each option, please refer to Configuration Data.

Here is a configuration example that illustrates a mixed implementation of Tealium’s utag alongside Google’s dataLayer:

JavaScript

{
  "ROOT_VARIABLE": ["utag:data"],
  "VARIABLES_DELIMITER": ":",
  "SITE_VARIABLES": ["event_data", "page_url"]
  "TRACK_DATALAYER_VARIABLES": {
      utag: {
        pageInfo: [1, 4],
        productInfo: [2],
      },
      dataLayer: {
        currency: [2],
        items: [2]
      },
    },
  "GOOGLE_CONFIGURATION": {
    "DISPATCH_DATALAYER_UPDATED_EVENT": true,
    "EVENT_ATTRIBUTE_LIST": {
      add_to_cart: [
          'currency',
          'item_category',
          'item_brand',
          'item_id',
          'item_name',
          'coupon',
          'value',
          'price',
          'discount',
          'quantity',
        ],
      begin_checkout: [
          'currency',
          'item_category',
          'item_category2',
          'item_brand',
          'item_id',
          'item_name',
          'coupon',
          'value',
          'price',
          'discount',
          'quantity',
          'brand',
        ],
    },
    "GOOGLE_DATALAYER_NAME": "dataLayer"
  },
}

Teavaro’s fcDataLayer

Teavaro’s fcDataLayer is defined at window.fcDataLayer and includes the following fields:

JavaScript

"permission" : {},
"notification" :{},
"page" : {},
"action" : [{}],
"query_params" : {},

permission and notification is used by Teavaro Consent Manager and records the consent notification and corresponding consents' / permissions' acceptance or rejection.
page records information about the visited page including name and URL.
action records actions of Teavaro Consent Manager and Popup Manager including views and clicks.
query_params includes data from the TRACKING_URL_QUERY_PARAMETERS configuration entry. The data is sent as an object, each key will contain an array of values derived from the query parameters, e.g: {key: [value]}.

Configuration

To enable this feature, the following configuration must be set to true:

JavaScript

const CALLS_CONFIG = {
  ...
  callsToMake: {
    info: {
      ...
      fcTrack: true, // process the queue using info-track call
      ...
    }
  }
  ...
}

With this configuration you can set the interval of tracking calls sending events in the queue:

JavaScript

const FC_CONF = {
  ...
  INTERVAL_IN_MILLISECONDS: 10000; // interval in ms to process events in the queue, default to 5000
  ...

Sample:

JSON

{
  "permission": {
    "CS-UTIQ": true
  },
  "notification": [
    {
        "name": "MAIN_CS",
        "version": 1,
        "permissions": [
            "CS-OM",
            "CS-OPT",
            "CS-NBA"
        ],
        "date": "1715675955904"
    }
  ],
  "action": [
    {
      "name": "ui_interaction",
      "action": "click",
      "category": "consent",
      "label": "accepted",
      "timestamp": 1715756684073
    }
  ],
  "page": {
    "timestamp" : "1713895860",
    "name": "Hillshire Farm Lit’l Smokies Salchicha ahumada, 14 oz",
    "action": "navigation",
    "url": "https://web.brand-demo.com/product/hillshire-farm-litl-smokies-salchicha-ahumada-14-oz/"
  },
  "product": {
    "name": "/product/hillshire-farm-litl-smokies-salchicha-ahumada-14-oz/",
    "action": "view",
    "pricing": "€5.31"
  },
  "campaign": [
    {
      "name": "20252883263",
      "source": "Google",
      "medium": "cpc",
      "id": "a74d8886-5df9-4baa-b776-166b3bf9111c"
    }
  ]
}

Teavaro provides a Popup Manager, which can be used for example to ask people to sign up to email newsletter, submit a request or answer a question. It can be configured to respond to specific user profile attributes handled by the web SDK. Information submitted can also be captured via the web SDK and passed on by the Data Activation Hub.

The popup UI can be configured using predefined templates and applying styling and branding as needed.

Tag Enablement

HTML

<script>
(function() {
  function load(src, callback) {
    var promise = new Promise(function(resolve) {
      var s = document.createElement('script');
      s.src = src;
      s.async = false;
      s.onload = s.onerror = resolve;
      (document.head || document.documentElement).appendChild(s);
    });
    if (callback) {
      promise.then(callback);
    }
    return promise;
  }
  load('https://{sub-domain}.{domain-name}/{domain-name, dot(s) are hyphenated}.js', function() {
    load('https://{sub-domain}.{domain-name}/fcTag.js');
    load('https://{sub-domain}.{domain-name}/teavaroPopupManager.js');
  });
})();
</script>

Each popup template is defined as a JSON file. The following table describes every supported configuration entry.

JSON

{
  "layout": {
    "container": "ImageToText",
    "position": "center"
  },
  "colorTheme": "test-brand-demo",
  "teavaroLogoUrl": "",
  "headline": "Heading Here Can be Big",
  "acceptButtonText": "Get the Item",
  "imageUrl": "https://i.postimg.cc/pTZQPmx4/unsplash-5e-XXD1-ACc8k.png",
  "imageMobileUrl": "https://i.postimg.cc/QCdQCjdt/image-6.png",
  "mobileBreakpointWidth": "400",
  "closeButtonImageUrl": "",
  "description": "Here is a brief description of the content",
  "bottomText": {
    "content": "You accept our {{Privacy Policy}}",
    "hyperLink": "https://google.com"
  },
  "inputPlaceHolder": "Enter your email",
  "additionalInput": {
    "name": "name",
    "inputPlaceHolder": "Enter your name"
  }
}

layout.container

Type: ImageToText | TextToImage
Description: Defines the overall popup layout. ImageToText displays the image before the text content, while TextToImage displays the text before the image.
Default: ImageToText

layout.position

Type: center, top-center, top-left, center-left, bottom-left, bottom-center, bottom-right, center-right
Description: Defines where the popup is displayed on the screen.
Default: center

colorTheme

Type: String
Description: Theme identifier used to assign predefined CSS styles to each popup. Setting this property adds a class to the rendered elements for popup customization.

teavaroLogoUrl

Type: String
Description: URL of the logo displayed inside the popup. Leave empty if no logo should be shown.

headline

Type: String
Description: Main title displayed in the popup.

description

Type: String
Description: Main descriptive text displayed below the headline.

acceptButtonText

Type: String
Description: Text displayed on the primary action button.

imageUrl

Type: String
Description: URL of the desktop image displayed in the popup. If no image is provided, a default value will be used

imageMobileUrl

Type: String
Description: URL of the image displayed on mobile devices. If omitted, the desktop image is used.

mobileBreakpointWidth

Type: String
Description: Maximum viewport width (in pixels) at which imageMobileUrl replaces the desktop image. If omitted, the Popup Manager default breakpoint is used.
Default: 400px

closeButtonImageUrl

Type: String
Description: URL of a custom close button icon. Leave empty to use the default close icon.

bottomText.content

Type: String
Description: Optional text displayed below the action button. Hyperlinks can be embedded using the syntax {{Link Text}}.

bottomText.hyperLink

Type: String
Description: URL associated with the hyperlink placeholder contained in bottomText.content.

inputPlaceHolder

Type: String
Description: Placeholder text displayed inside the email input field.

additionalInput.name

Type: String
Description: Identifier of an optional additional input field. This value is used to generate the HTML input element ID.

additionalInput.inputPlaceHolder

Type: String
Description: Placeholder text displayed inside the optional additional input field.

Notes

bottomText is optional and may be omitted.
additionalInput is optional and is intended for templates that require collecting an additional value (for example, a name or phone number).
imageMobileUrl and mobileBreakpointWidth are optional. If not provided, the desktop image and default breakpoint are used.

Client Configuration

To setup the Popup Manager, the following parameters need to be added to the client configuration file:

JavaScript

//  client config file sample
POPUP_CONFIG: {
  ENABLED: boolean;
  EMAIL_VERIFICATION_URL_PARAMETERS: string[];
  ENCRYPTED_EMAIL_KEY: string;
  VERIFICATION_URL: string;
  CONFIRMATION_URL: string;
  ENCRYPTION_URL: string;
  OPENING_DELAY: number;
}

ENABLED: boolean: The boolean value provided is used to set the enablement status of the Popup Manager.

VERIFICATION_URL: string: The value is used to call the backend API URL to verify the email address is a valid email address.

ENCRYPTION_URL: string: The parameter is used as the backend API URL to encrypt the user email address value.

CONFIRMATION_URL: string: The parameter is used as the backend API URL to confirm that the provided email address is recognized by the website owner.

ENCRYPTED_EMAIL_KEY: string: The key name in sessionStorage is where the encrypted email is saved. This value will be compared and must match, with the encrypted value in the URL.

EMAIL_VERIFICATION_URL_PARAMETERS: string[]: An array containing all the parameters required to be present in the URL to validate the email.

OPENING_DELAY: number: Time in seconds between the configured popups, default to 5

Example:

JavaScript

POPUP_CONFIG: {
  ENABLED: true,
  EMAIL_VERIFICATION_URL_PARAMETERS: ['subemail', 'emailverify'],
  ENCRYPTED_EMAIL_KEY: 'xenemail',
  ENCRYPTION_URL: '',
  OPENING_DELAY: 5,
  VERIFICATION_URL: '';
  CONFIRMATION_URL: '';
},

Reference

JavaScript API

The JavaScript API is enclosed within Teavaro namespace and can be used in any JavaScript snippet after the fcTag.js is loaded successfully. It provides multiple functionalities that can be used to achieve specific goals or improve data and flow analysis.

getFcDataEntry

getFcDataEntry method provides access to data from the client (browser). It accepts the following entry keys as a param: umid, attributes, identifiers, permissions, permissionsLastModification, notificationHistory, and notificationStatus. In case of error, null value is returned, and a descriptive error message is shown to the user via console.

Example:

JavaScript

Teavaro.API.getFcDataEntry('attributes', 'umid')

Return types: object key-value-pairs.

Return values (input-based):

null for errors.

umid: e.g. { umid: c3641a83-3ae3-412f-b234-ea91cfaa3242 }

attributes example:

JSON

{
    attributes: {
        "browserFamily": "Chrome",
        "browserType": "BR",
        "browserVersion": "132.0.0.0",
        "cc": "DE",
        "city": "Frankfurt am Main",
        "deviceName": "PC",
        "domainName": "amazon.com",
        "isp": "A100 ROW GmbH",
        "latitude": "50.11088",
        "longitude": "8.681996",
        "usageType": "DCH",
        "mcc": "",
        "mnc": "",
        "mobileBrand": "",
        "osFamily": "Windows",
        "region": "Hessen",
        "nba1": "nba1",
        "nba2": "nba2",
        "attribute1": "value1",
        "attribute2": "value2",
        "fctk": "iBzk0liUOiM.1746803293605.pEPMj7DG4OChBwQCgy8Uk9MgfENQ254evuTUNkbF4hg"
    }
}

identifiers example:

JSON

{
    identifiers: [{
            "name": "fc_hemail",
            "value": "c98ba13fd5a342230e1e6c32d2bef7cc36d3125cce987ad3ecd5e6de3631dfea"
        },
        {
            "name": "fc_hcid",
            "value": "f6fa4edf58d07bb14de6f731eebc37e122a44c760bbc2e4ce982d106accbf791"
        }
    ]
}

permissions example:

JSON

{
    permissions: {
        "CS-OM": true,
        "CS-OPT": true,
        "CS-NBA": true
    }
}

permissionsLastModification example:

JSON

{
    permissionsLastModification: {
        "CS-OM": "2024-06-19T16:17:41.607Z",
        "CS-OPT": "2024-06-19T16:17:41.607Z",
        "CS-NBA": "2024-06-19T16:17:41.607Z"
    }
}

notificationHistory example:

JSON

{
    notificationHistory: {
        "name": "MAIN_CS",
        "version": 1,
        "permissions": [
            "CS-OM",
            "CS-OPT",
            "CS-NBA"
        ],
        "date": "2024-06-19T16:17:41.607Z"
    }
}

notificationStatus example:

JSON

{
    notificationStatus: {
        "CS-NBA": true,
        "CS-OM": true,
        "CS-OPT": true,
        "CS-UTIQ": false
    }
}

Using multiple keys in one call:

Teavaro.API.getFcDataEntry('umid', 'identifiers');

Response:

JSON

{
    "umid": "b79fc820-70fc-4f03-8613-9887552d2b19",
    "identifiers": [{
            "name": "mt1",
            "value": "mt1-67h2p9VVPK2RWwuK7UJVSg"
        },
        {
            "name": "mt2",
            "value": "mt2-L8NMTaL2Ee2DSrWyuwgESA"
        },
        {
            "name": "customerId",
            "value": "003Td00000GSxn9IAD"
        },
        {
            "name": "email_sha256",
            "value": "a684079545719bb06100288b8ad5c97b0d2223935beb42eda37abedd4b074aca"
        }
    ]
}

showConsentManager

This method opens the Teavaro Consent Manager notification popup.

JavaScript

Teavaro.API.showConsentManager()

Example use:

JavaScript

<button onclick="Teavaro.API.showConsentManager()">Teavaro Consent Manager</button>

setVerboseLoggingLevel

This method sets the logging level to verbose to enable extended logging. This logging level includes DEBUG and TRACK messages, granting more information that can be used to get specific information about any flow step or provide more information about an underlying issue. The logging level is saved to the browser’s local storage, so the extended logs will be enabled as long as the entry is in the local storage. It can be re-set to the default value by using resetLoggingLevel method explained below.

JavaScript

Teavaro.API.setVerboseLoggingLevel()

Return type: none

Return values: none

This method logs [FC_TAG]: [INFO] Verbose logging level has been set message, that indicates the logging level has been set successfully.

resetLoggingLevel

This method re-sets the logging level to the default from any other logging level by removing logging level local storage entry. Default logging level includes only ERROR, WARNING and INFO messages, which provides sufficient information about the operations that are happening as the flow progresses. This method does not need to be called to enable the default logging, as it is enabled as soon as the fcTag.js loads. It can be used to re-set the logging level set by setVerboseLoggingLevel.

JavaScript

Teavaro.API.resetLoggingLevel()

Return type: none

Return values: none

This method logs [FC_TAG]: [INFO] Logging level has been reset to info level message, that indicates the logging level has been set back to default successfully. If the verbose logging level was set beforehand, it could also show couple of other entries mentioning value of the current logging level, that is set in browser’s local storage.

addEventListener

This method attaches a custom callback to our defined events

JavaScript

Teavaro.API.addEventListener(eventName: string, callback: any)

Return type: none

Return values: none

JavaScript

Teavaro.API.addEventListener('onFcDataAvailable', ({notificationStatus, permissions, attributes, state, identifiers}) => {
  // execute a custom callback
})

Events

onFcDataAvailable

If you want to fetch the latest data from fcData, using the event listener to trigger your API call would be the recommended solution, as it ensures you get the latest data directly after it has been updated.

This event is fired right after the call has updated fcData localStorage with the newest attributes, including:

Attribute name	Type
`attributes`	JSON object with key-value-pairs using string data type.
`identifiers`	JSON array of objects with name and value key-value-pairs, all using string data type.
`permissions`	JSON object with key-value-pairs, using boolean values.
`notificationStatus`	JSON array with object.
`state`	Key-value-pair with numeric value.

JavaScript

window.Teavaro = window.Teavaro || {};
window.Teavaro.config = {
    listeners: {
        onFcDataAvailable: ({
            attributes,
            identifiers,
            notificationStatus,
            permissions,
            state,
        }) => {
            // Single callback action
           }
    }
};

Configuration Data

The Web SDK provides extensive configuration capabilities defined in client and domain-specific config files.

Endpoints Configuration

API_HOST

string full host with the path of Teavaro’s API endpoint, e.g. https://fc.yourdomain.com/op.

IDCONNECT_API_HOST

string full IdConnect host with path, e.g. https://fc.yourdomain.com/op/idconnect.

SCRIPT_SUBDOMAIN

string value used to load the templates from a specific subdomain for consent manager and popup manager modules. If properly set up, the templates will be loaded from https://SCRIPT_SUBDOMAIN.your-domain.com/teavaro/templates/template-name-tmpl.js. The default is fc.

Calls Configuration

conditions

object to configure how the calls will behave, per session or per time interval.

JavaScript

conditions: {
    timeConditions: {
        oncePerSession: false,
        oncePerTimeInterval: null, // Time in MS or null
    },
    oncePerPage: true,
    urls: null,
}

oncePerSession

boolean value defining if the calls should be made once per user session instead of every library load into the browser.
is superseded by oncePerTimeInterval and callsPerPage configuration, explained below.

oncePerTimeInterval

null or number value defining the interval after which the session calls should be made again.
null value means that the setting won’t be checked.
number value should be represented in milliseconds, e.g. null / 60000.

info

Optional object types:
- track property in the info object determines if the info call will be used for tracking 3rd party dataLayers, such as Tealium’s utag or Google’s dataLayer.
- fcTrack property in the info object determines if the info call will be used for tracking Teavaro’s fcDataLayer, the events, are sent as batches.
- fcTrackSpaNavigation property in the info object to enable tracking page visits on Single Page Applications via the fcDataLayer queue.
- consent_umid property in the info object enables the umid as lookup id for FunnelConnect. For this feature to work the website will have to store the umid in consent_umid key in session storage beforehand.
- ident property to retrieve customer identifiers from different browser storage locations including data layer, session or local storage, cookies, etc.
  - customerId can be either a function that returns a string or a number or an object if the identifier is stored in a JWT token cookie or in a base64 cookie. For identifiers consisting of PII, for example email address, stored in JWT cookies. To enable decoding identifiers from a base64 cookie, add the optional boolean isBase64 to the customerId entry.
  - customerKey is the value used as the key of the identifier in the query string payload.
  - dataLayer, if provided the identifier will be loaded from the configured data layer. e.g: dataLayer
  - shouldHash, if provided, it allows hashing the related identifier using sha256. Note: the identifier will first be converted to lowercase and then hashed.

JavaScript

//configuration example for ident

const findCustomerId = () => window.sessionStorage.getItem('enemail');

ident: [
  {
    customerId: {
      cookie: '[cookie name]',
      identifierName: '[identifier name captured from JWT value]',
    },
    customerKey: 'e10',    // Parameter to pass customer ID.
    },
  {
    customerId: {
      cookie: '[cookie name]',
      identifierName: '[identifier name captured from the base64 value]',
      isBase64: true, // enable the feature to read the identifier from the base64 cookie
    },
    customerKey: 'e10',    // Parameter to pass customer ID.
    },
  {
    customerId: {
      cookie: '[cookie name]',
      identifierName: '[identifier name captured from JWT value]',
    },
    customerKey: 'e11',    // Parameter to pass hashed email.
    shouldHash: true,    // value is hashed using sha256
    },
  {
    customerId: findCustomerId(),    // Function to obtain customer ID from local storage, cookie or data layer.
    customerKey: 'enemail_key',
    getCustomerId: findCustomerId    // Optional retry to capture customer ID on subsequent page load.
  },
  { 
    customerId: 'accountID', // this is the key where the identifier is located in the dataLayer 
    customerKey: 'accountID', //this is the key that will be used to send the identifier in the info-ident payload 
    dataLayer: 'utag', //this is the dataLayer where the identifier is located 
  }
],

idConnect

boolean value defining whether the idConnect calls flow should be made. false value means that the idConnect calls flow won’t be done at all, while true value means that the calls flow will be done.

subscribe

boolean or object value defining whether the track call should be made and with what parameters. false value means that the track call won’t be done at all, while true value is not supported, it must be specified with object value following this pattern:

JavaScript

{
    subscriberId: window.sessionStorage?.subemail,
    subscriberKey: 'enemail',
},

callsPerPage

A collection of boolean values determines which calls should be enabled or disabled according to the CALLS_CONFIG.conditions entry. Any calls marked as “true” will be executed upon each reload of the JavaScript library.
- Note: the configuration for each call enabled here will be read from the corresponding callsToMake entry.

JavaScript

callsPerPage: {
      info: true,
      idConnect: false,
      idConnectInfo: false,
      floodlight: false,
      facebook: false,
      idsync: false,
    },

API_INFO_URL

string value of pipeline path for Info Ident Track calls. This will be appended to API_HOST, e.g. /brand-demo-info/info.

API_INFO_URL_PARAMETERS

array of strings containing the FunnelConnect query string parameters. Valid entries are 'attributes', 'notifications', 'permissions', 'nbidentifiers' 'identifiers'. If there is any invalid entry, the library will log the name(s) in the browser’s console and exclude them, e.g. ['attributes', 'notifications', 'permissions', 'identifiers']. If the entry is not configured, all valid entries will be used.

API_SUBSCRIBE_URL

string value of pipeline path for Info Ident Track calls. This will be appended to API_HOST, e.g. /brand-demo-newsletter/v1/subscribe.

IDR

ident enables you to configure also the capture of lookup identifiers from a JWT token. It provides also a hashing function to hash PII before sending it in query string parameter.

JavaScript

ident: [
  {
    customerId: {
      cookie: '[cookie name]',
      identifierName: '[identifier name captured from JWT value]',
    },
    customerKey: 'e10',    // Parameter to pass customer ID.
    },
  {
    customerId: {
      cookie: '[cookie name]',
      identifierName: '[identifier name captured from JWT value]',
      shouldHash: true,    // value is hashed using sha256
    },
    customerKey: 'e11',    // Parameter to pass hashed email.
    }
],

Multiple identifiers can be provided.

findCustomerId and CALLS_CONFIG constants can be configured to handle any customer identifier from local storage or data layer as part of the IDR.

JavaScript

...
const findCustomerId = () =>
    window?.dataLayer?.[0].clientinfo?.clientcustomerid;
...
const CALLS_CONFIG = {
        callsPerPage: {
            info: {
                ident: [
                  {
                      customerId: findCustomerId(),
                      customerKey: 'customerId',
                  }
                ]
            }
        }

IDR_QUERY_PARAMETERS

array of strings is to be read from the URL and added to the Info Ident Track call payload, those values must exist in the URL as query string parameters. This can be used to pass a user identifier when redirected from/to a different website, for example someone clicking on an email campaign link. See definition of IDR query string parameters.

JavaScript

IDR_QUERY_PARAMETERS: ["e10cp", "e11cp"],

Utiq

Defined via callsPerPage config within info object for Info Ident Track call. It gets the martechpass (mtid) via onIdsAvailable event listener.

JavaScript

callsPerPage: {
    info: {
        utiq: {
            marTechPassMobileKey: 'mt1',
            marTechPassFixedKey: 'mt2',
        }
    }
}

marTechPassMobileKey defines the mobile connection martechpass.
marTechPassFixedKey defines the fixed (Wifi) connection martechpass.

cookieParams property allows reading cookies to be sent as URL encoded query string parameters with the Info Ident Track call. Two types of cookie values can be captured:

cookie_name specify the cookie you want to read and take the full value.
cookie_param specify the parameter within the cookie value you want to capture.

JavaScript

//configuration for cookie value

cookieParams: [ 
  { 
    cookie_name: '[cookie name]'
  },
],

//configuration for specific parameter from cookie value

cookieParams: [ 
  { 
    cookie_name: '[cookie name]',
    cookie_param: '[specific parameter to be captured within cookie value]'
  },
],

CONSENT_COOKIE_CONFIG

object to enable the creation of a cookie used with cross-domain IDR via CDN (e.g. CloudFront, etc.) when consent is granted. The web SDK will only be loaded after cookie consent has been granted.

JSON

{
    enabled: true;
}

Data Storage

STORAGE_KEY

string: name of the key where the response of the Info Ident Track call will be stored, e.g. fcData.

STORAGE_TYPE

string value determines where is going to be stored the STORAGE_KEY. Default to sessionStorage, e.g. localStorage|sessionStorage.

Tracking Query Parameters

TRACKING_URL_QUERY_PARAMETERS

array of strings is to be read from the URL and added to fcDataLayer.query_params is to be sent as batches via info-track call and to localStorage’s fcData.attributes, those values must exist in the URL as query string parameters.
e.g. ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content']

Data Layer Data Capture

ROOT_VARIABLE

array of strings of the 3rd party dataLayers. Note, if known beforehand, you can also provide a specific nested key where the required SITE_VARIABLES are defined. Note: If the website has installed Google Tag Manager/ Google Analytics, the dataLayer name must be configured in GOOGLE_CONFIGURATION entry, e.g. ['utag', 'wpDataLayer'] using VARIABLES_DELIMITER: ['utag:data', 'wpDataLayer'].

VARIABLES_DELIMITER

string value used to navigate through the dataLayer object, e.g. ':'

rootVariablesRetryPeriod

number timeout value used to retry retrieving the source object for a path. Used alongside ROOT_VARIABLE and VARIABLES_DELIMITER, e.g. '500'.

SITE_VARIABLES

array of strings of the variable's name that is going to be tracked from the ROOT_VARIABLE, e.g. ['event_data', 'page_url', 'shortcode_identifier'].

INTERVAL_IN_MILLISECONDS

number time in milliseconds to check for events in the fcDataLayer’s queue and execute the info-track call. The default is 5000 ms.

TRACK_DATALAYER_VARIABLES

object containing the 3rd party dataLayers and a set of variables at a specific level. The results will contain the full object under the configured key and will be sent via post method in the Info Ident Track payload under a data key. If the configured variable name is not found under a specific level, the library will log to the browser console the variable name and level number, helping with the debugging.

JavaScript

TRACK_DATALAYER_VARIABLES: {
    anyDataLayer1: {
        anyVariable1: [1, 2],
        anyVariable2: [3],
    },
    // note: for objects wrapped inside arrays, an extra level must be added
    anyDataLayer2: {
        anyVariable1: [2],
    },
},

Configuration example:

JavaScript

TRACK_DATALAYER_VARIABLES: {
    dataLayer: {
        pageInfo: [1, 4, 2],
        productInfo: [2],
    },
}

Payload example:

JSON

{
  "data": [
      [
        {
            "pageInfo": {
                "pageName": "ar:pdp:9399640:argoshomeheathdonsingleendliftottomanbed-grey:",
                "siteSection": "ar:productdetails:",
                "categoryID": [
                    "29351",
                    "29366",
                    "29865",
                    "29867"
                ]
            }
        },
        {
            "pageInfo": {
                "visited": "true"
            }
        },
        {
            "productInfo": {
                "productID": "9399640",
                "productName": "Argos Home Heathdon Single End Lift Ottoman Bed - Grey"
            }
        },
      ]
  ]
}

Google Analytics

GOOGLE_CONFIGURATION

object to configure Google-related configuration

JavaScript

GOOGLE_CONFIGURATION: {
    DISPATCH_DATALAYER_UPDATED_EVENT ? : boolean;
    EVENT_ATTRIBUTE_LIST ? : EventAttributeList;
    GOOGLE_DATALAYER_NAME: string;
    UMID_TO_DATALAYER_CONFIGURATION ? : {
      UMID_PUSH_EVENT_NAME?: string;
      UMID_KEY_NAME?: string;
    };
}

DISPATCH_DATALAYER_UPDATED_EVENT

boolean value used to attach a listener event to Google’s dataLayer defined in GOOGLE_DATALAYER_NAME entry, if set to true, an info-track call is triggered after every push event if any of the EVENT_ATTRIBUTE_LIST or SITE_VARIABLES are found in the new pushed data.

EVENT_ATTRIBUTE_LIST

object value in which each key is the event name to track and the value is an array with the event's attributes. This allows us to capture Google-recommended events.

JavaScript

EVENT_ATTRIBUTE_LIST: {
    ...
    event_name: ['attribute1, attribute2,'....],
    ...
}

GOOGLE_DATALAYER_NAME

string value to define the name of Google’s dataLayer.
For configuration example please check here.
Payload example:

JSON

{
  "add_to_cart": {
    "currency": "EUR",
    "value": "45.50",
    "items": [
      {
        "item_category": "Fish",
        "item_id": "",
        "item_name": "TSARINE Caviar 50g",
        "coupon": "",
        "affiliation": "",
        "price": "45.50",
        "discount": 0,
        "quantity": 1
      }
    ]
  }
}

UMID_TO_DATALAYER_CONFIGURATION

object value to enable pushing the umid as an event into Google’s dataLayer. In case the umid changes due to identification, this change will be reflected in the dataLayer, allowing GTM calls to contain the latest umid value. This is useful when the umid is required to be used as a parameter of a GTM tag or as a main identifier for users in Google Analytics.
- UMID_PUSH_EVENT_NAME string value to configure the event name. If not provided, umid_updated is used by default.
- UMID_KEY_NAME string value to configure the key name under which the umid will be stored. If not provided, user_id is used by default.

JavaScript

UMID_TO_DATALAYER_CONFIGURATION: {
  UMID_PUSH_EVENT_NAME: 'umid_updated',
  UMID_KEY_NAME: 'user_id',
},

To integrate this feature with GTM:
- Create a trigger of type Custom Event.
- Use the same name configured in UMID_PUSH_EVENT_NAME as the event name.
- Create a Data Layer variable using the name configured in UMID_KEY_NAME
- In the desired Tag, add a new parameter and provide the desired name to be used in Google Analytics as a value of the previously created Data Layer variable.

Matomo

MATOMO_CONFIGURATION

object containing the configuration to integrate a listener callback to Matomo’s dataLayer. If configured, an info-track call is triggered after every push event if any of the SITE_VARIABLES are found in the new pushed data.

PUSH_FUNCTION_CONTAINER

string value of the direct push function’s container. For Matomo, the push function is located in window._mtm.push(), provide the direct parent entry of the desired push function, in this case: _mtm.

DISPATCH_DATALAYER_UPDATED_EVENT

boolean value to enable/disable the feature.

"MATOMO_CONFIGURATION": {
  "PUSH_FUNCTION_CONTAINER": "_mtm",
  "DISPATCH_DATALAYER_UPDATED_EVENT": true,
},

IDConnect Cross-domain

IDCONNECT_MANUAL_ROUTING

boolean entry to enable setups with cross-domain calls

IDCONNECT_NEXT_BEST_DOMAIN

string of the hostname for the sub-domain, which will be used as a 3rd party domain for cross-domain calls, fc.yourdomain.com.

IDCONNECT_DATA_STORAGE

string value defines the browser storage key name where data from FunnelConnect will be stored.
default value is set to “fcIdConnectData“.

IDCONNECT_STORAGE_TYPE

string value which defines the browser storage type will be used to create the IDCONNECT_DATA_STORAGE.
possible values are “sessionStorage“ and “localStorage“.

IDCONNECT_TYPE

string value which defines the idconnect use case that will be run.
default value is set to “crossdomain“.

IDCONNECT_ALLOW_TOKEN_DATA_CALL

boolean value defines whether the additional token call should be triggered in the flow.
default value is set to “false“.

IDCONNECT_ALLOW_TOKEN_DATA_CALL_COUNTER

integer value that defines the number of times the token call should be done.
default is set to “false“.

POPUP_CONFIG

object containing the common configuration for the popups.

CAMPAIGN

string value is used to identify the campaign the user has been assigned to via FunnelManager.

CAMPAIGN_STORAGE

string prefix to store in configured browser storage whether the popup has been submitted or discarded. E.g. if accepted, the stored value will be popupCampaign__true if rejected popupCampaign__fales

ENABLED

boolean value to enable/disable the popup

VERIFICATION_URL

string

ENCRYPTION_URL

string value of the URL endpoint to encrypt the email.

CONFIRMATION_URL

string value of the URL to which the user will be redirected. Once submitted the popUp, this value will be stored in the configured browser’s storage for later validation using the key CONFIRMATION_URL.

ENCRYPTED_EMAIL_KEY

string value of the key where the encrypted email will be stored, this key should be present as a query string parameter in the CONFIRMATION_URL. Once submitted the popUp, the value of this entry will be the key for the encrypted email in the configured browser’s storage for later validation.

JavaScript

[
  {
      CAMPAIGN: 'email-1',
      CAMPAIGN_STORAGE: 'popupCampaign',
      ENABLED: true,
      VERIFICATION_URL: '',
      ENCRYPTION_URL: 'https://encryption-api.test.teavaro.systems/api/v1/encr/test1',
      CONFIRMATION_URL: 'https://www.brand-demo.com/thank-you/',
      EMAIL_VERIFICATION_URL_PARAMETERS: ['subemail', 'emailverify'],
      ENCRYPTED_EMAIL_KEY: 'xenemail',
  },
  {
      ...
  }
]

ID Sync / Matching

API_IDSYNC_URL

string value for the idSync service pipeline.

META_TAGS

array of string of meta tags to look in the website public variables.

FLOODLIGHT_ID

string value for the floodlight service identification.
default is set to “nectarFloodlight“.

API_FLOODLIGHT_PATH

array of string values defining the floodlight service pipelines.

API_FACEBOOK_URL

string value for the facebook service pipeline.

FACEBOOK_IFRAME_ID

string value defines the id of the iframe which loads the Facebook service.

FACEBOOK_ID

string value defines the Facebook service identification.

Getting Started

Integration via Tag Manager

Consent Management

CMP Integration

Teavaro Native CMP

Tag Enablement

Notification Template Configuration

Theme Customization

Data Layer Data Capture

Google and other Data Layers

Teavaro’s fcDataLayer

Teavaro Popup Manager

Tag Enablement

Popup Template Configuration

Client Configuration

Reference

JavaScript API

getFcDataEntry

showConsentManager

setVerboseLoggingLevel

resetLoggingLevel

addEventListener

Events

onFcDataAvailable

Configuration Data

Endpoints Configuration

Calls Configuration

IDR

Utiq

Cookie Consent

Data Storage

Tracking Query Parameters

Data Layer Data Capture

Google Analytics

Matomo

IDConnect Cross-domain

Popup Manager

ID Sync / Matching