Skip to main content
Skip table of contents

Web SDK

Overview

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. Please also confirm if you are using subdomains, as we will need to enable them.

Our default setup uses A record, and depending on your region, we will provide you with the addresses for your DNS setup.

If you are using CAA records, you must allow the letsencrypt.org domain on all the subdomains created for the Teavaro service. More information you find in the Let’s Encrypt CAA records documentation.

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

Getting Started

The web SDK configuration is automatically obtained through the fcTag.js execution via the specified domain.

For example this tag would automatically load brand-demo-com.js.

JS 
(function(){
 var script = document.createElement("script")
 script.type = "text/javascript"
 script.src = "https://fc.{your domain}/fcTag.js"
 document.head.appendChild(script)
})();

Integration via Tag Manager

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

JS 
<script>  
(function(){
 var script = document.createElement("script")
 script.type = "text/javascript"
 script.src = "https://fc.{your domain}/fcTag.js"
 document.head.appendChild(script)
})();
</script>

Consent Manager 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.

Teavaro Consent Management

Teavaro provides a server-side consent management capability, which lets you define any type of data collection and processing purpose.

We also provide a consent notification, which can be enabled using teavaroConsentManager.js.

The custom HTML tag including our consent manager would be:

JS 
<script>  
  (function(){
    // load client config file
    var clientConfigScript = document.createElement('script'); 
    clientConfigScript.type = 'text/javascript';
    clientConfigScript.src = 'https://fc.{domain-name}/{domain-name, dot(s) are hyphenated}.js"';
    
    document.head.appendChild(clientConfigScript).onload = function(){
      // load teavaroConsentManager.js
      var teavaroConsentManagerScript = document.createElement('script');
      teavaroConsentManagerScript.type = 'text/javascript';
      teavaroConsentManagerScript.src = 'https://fc.{your domain}/teavaroConsentManager.js';
      document.head.appendChild(teavaroConsentManagerScript);
    }();
  })();
</script>

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.

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

JS 
{
  "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"
  },
}

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:

JS 
{
  "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"
  },
}

Reference

JavaScript API

The FunnelConnect JavaScript API is enclosed within Teavaro namespace that can be used in any JavaScript snippet after the fcTag.js was 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 CDP for 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 usage:

JS 
Teavaro.API.getFcDataEntry('attributes')

Return types: string, object, key-value-pairs.

Return values (input based):

null for errors.

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

attributes: object e.g.

JSON 
{
    "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"
}

identifiers: array e.g.

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

permissions: object e.g.

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

permissionsLastModification: object e.g.

JSON 
{
  "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: array e.g.

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

notificationStatus: object e.g.

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

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. 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.

Example usage:

JS 
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.

Example usage:

JS 
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.

Events

onFcDataAvailable

This event is fired right after the call has updated localStorage with the newest attributes, which could be: attributes, notificationStatus, permissions, state, and identifiers.

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

Configuration Data

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

Endpoints configuration:

  • API_HOST

    • string of full Funnel Connect host with path

    • e.g. https://funnelconnect.brand-demo.com/op

  • IDCONNECT_API_HOST

    • string of full IdConnect host with path

    • e.g. https://idc.brand-demo.com/op/idconnect

  • IDCONNECT_MANUAL_ROUTING

    • boolean entry to enable setups with cross-domain calls

    • e.g. true

  • IDCONNECT_NEXT_BEST_DOMAIN

    • string of the hostname for the domain including Funnel Connect, that will be used as a 3rd party domain for cross-domain calls

    • e.g. funnelconnect.publisher-demo.media

  • API_INFO_URL

    • string value of pipeline path for Info Ident Track calls

    • e.g. /brand-demo-info/info

    • (optional)

  • STORAGE_KEY

    • string: name of the key where the response of the Info Ident Track call will be stored

    • e.g. fcData

    • (required)

  • STORAGE_TYPE

    • string value determine where is going to be stored the STORAGE_KEY. Default to sessionStorage

    • e.g. localStorage|sessionStorage

    • (optional)

  • API_TRACK_URL

    • string value of pipeline path for Track calls

    • e.g. /brand-demo-track/track

    • (optional)

  • API_SUBSCRIBE_URL

    • string value of pipeline path for Info Ident Track calls

    • e.g. /brand-demo-newsletter/v1/subscribe

    • (optional)

  • 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']

    • (optional)

  • VARIABLES_DELIMITER

    • string value used to navigate through the dataLayer object

    • e.g. ':'

    • (optional)

  • rootVariablesRetryPeriod

    • number timeout value used to retry retrieving the source object for a path. Used alongside ROOT_VARIABLE and VARIABLES_DELIMITER

    • e.g. '500'

    • (optional)

  • SITE_VARIABLES

    • array of strings of the variable's name that is going to be tracked:

    • e.g. ['event_data', 'page_url', 'shortcode_identifier']

    • (optional)

  • SCRIPT_SUBDOMAIN

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

    • e.g. fctag

    • (optional)

  • GOOGLE_CONFIGURATION

    • object to configure Google-related configuration

    • (optional)

    • e.g.

JS 
GOOGLE_CONFIGURATION: {
    DISPATCH_DATALAYER_UPDATED_EVENT?: boolean;
    EVENT_ATTRIBUTE_LIST?: EventAttributeList;
    GOOGLE_DATALAYER_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, a track call is triggered after every push event

    • e.g. true

  • EVENT_ATTRIBUTE_LIST

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

  • GOOGLE_DATALAYER_NAME

    • string value to define the name of Google’s dataLayer.

    • (optional)

    • e.g. dataLayer

  • TRACK_DATALAYER_VARIABLES

    • object containing the 3rd party dataLayers and a set of variables at a specific level. The results will be sent via post method in the Info Ident Track payload under a data key.

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

  • (optional)

  • TRACKING_URL_QUERY_PARAMETERS

    • array of strings to be read from the URL and added into fcDataLayer.dataLayer and 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']

    • (optional)

  • INTERVAL_IN_MILLISECONDS

    • number time in milliseconds to check for events in the fcDataLayer.dataLayer’s queue and execute the track call. Default to 5000 ms

    • (optional)

  • POPUP_CONFIG

    • array of objects containing the configuration for the popups.

    • (optional)

    • eg:

JS 
[
  {
    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',
  },
  {
  ...
  }
]

  • CONSENT_COOKIE_CONFIG

    • object to enable the creation of a cookie to detect cross-domain on Cloudfront when consent is granted.

    • eg:

JS 
{
  enabled: true;
}

  • (optional)

  • IDCONNECT_DATA_STORAGE

    • string value which 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 define 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 ran.

    • default value is set to “crossdomain“.

  • IDCONNECT_ALLOW_TOKEN_DATA_CALL

    • boolean value that define wether 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 define the number of times the token call should be done.

    • default is set to “false“.

    • (optional)

  • API_IDSYNC_URL

    • string value for the idSync service pipeline

    • (optional)

  • META_TAGS

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

    • (optional)

  • FLOODLIGHT_ID

    • string value for the floodlight service identification

    • default is set to “nectarFloodlight“

    • (optional)

  • API_FLOODLIGHT_PATH

    • array of string values defining the floodlight service pipelines

    • (optional)

  • API_FACEBOOK_URL

    • string value for the facebook service pipeline

    • (optional)

  • FACEBOOK_IFRAME_ID

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

    • (optional)

  • FACEBOOK_ID

    • string value defines the Facebook service identification

    • (optional)

Calls configuration

  • conditions

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

    • eg:

JS 
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

    • e.g. true

  • 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

    • boolean or object value defining whether the info call should be made and what data should be provided

    • false value means that the info call won’t be done at all, while true value means that the call will be done with no additional data nor parameters

    • object type of value will require output from the backend team effort with the client setup and has the following structure and is fully dependent on the Funnel Connect or Utiq (if enabled) setup:

      • the optional track property in the info object determines if the info call will be used for tracking. E.g.: sain clients.

      • the optional 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.

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

{
        permissionsKeys: {
          onlineMarketing: 'CS-OM',
          nextBestAction: 'CS-NBA',
          optimisation: 'CS-OPT',
          utiq: 'CS-UTIQ', <--- KEYS AND VALUES HERE ARE DEPENDING ON BACKEND SETUP
        },
        notificationsData: [
          {
            name: 'MAIN_CS', <--- DEPENDING ON THE BACKEND SETUP
            version: 1,
            permissions: ['CS-OM', 'CS-OPT', 'CS-NBA'], <--- ARRAY CONTENT DEPENDING ON permissionKeys VALUES FROM ABOVE
          },
          {
            name: 'UTIQ_CS', <--- DEPENDING ON THE BACKEND SETUP
            version: 1,
            permissions: ['CS-UTIQ'], <--- ARRAY CONTENT DEPENDING ON permissionKeys VALUES FROM ABOVE
          },
        ],
        ident: {
          customerId: findCustomerId(), <--- THIS FUNCTION(IMPLEMENTED ABOVE) IS DEPENDING ON THE SOURCE OF CUSTOMER ID FROM THE DATA AVAILABLE TO THE BROWSER
          customerKey: 'enemail', <--- DEPENDING ON THE BACKEND SETUP
          getCustomerId: findCustomerId <---- FUNCTION DEFINITION(WITHOUT THE PARENTHESIS). THIS IS OPTIONAL AND TRIES TO RESOLVE THE CUSTOMER ID IF IS NOT AVAILABLE ON THE FIRST PAGE LOAD
        },
        utiq: {
          marTechPassMobileKey: 'mt1',  <--- IF ENABLED, DEPENDING ON THE BACKEND SETUP
          marTechPassFixedKey: 'mt2',
        },
        track?: boolean,
        consent_umid?: boolean,
      },

  • track

    • boolean value defining whether the track call should be made

    • false value means that the track call won’t be done at all, while true value means that the call will be done

  • 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

    • object value must follow the pattern:

JS 
{
  subscriberId: window.sessionStorage?.subemail, <--- DEPENDING ON THE ACTUAL SOURCE OF THE SUBSCRIBER EMAIL
  subscriberKey: 'enemail', <--- DEPENDING ON THE BACKEND SETUP
},

  • utiq

    • boolean value defining whether the Utiq service should be called

    • false value means that the Utiq service won’t be called, while true value means that the Utiq service will be called at the end of the calls flow

    • currently working only with Teavaro Consent Manager setup

  • callsPerPage

    • supports the same configuration for the info, track, idConnect calls, but for the setups where those calls are required on every page load rather than oncePerSession or oncePerTimeInterval

    • all of the calls placed here with “true” or an object value will be launched on every JavaScript library reload

    • supersedes the oncePerSession and oncePerTimeInterval settings

  • callsToMake

    • similar to callsPerPage

    • the utiq entry in this object controls the integration of utiqLoader.js from the fcTag.js library.

    • eg:

JS 
callsToMake: {
  info: {
    permissionsKeys: {
      onlineMarketing: 'CS-OM',
      nextBestAction: 'CS-NBA',
      optimisation: 'CS-OPT',
      utiq: 'CS-UTIQ',
    },
    notificationsData: [
      {
        name: 'MAIN_CS',
        version: 1,
        permissions: ['CS-OM', 'CS-OPT', 'CS-NBA'],
      },
      {
        name: 'UTIQ_CS',
        version: 1,
        permissions: ['CS-UTIQ'],
      },
    ],
    ident: {
      customerId: findBrandDemoId(),
      customerKey: 'enemail',
    },
    utiq: {
      marTechPassMobileKey: 'mt1',  <--- IF ENABLED, DEPENDING ON THE BACKEND SETUP
      marTechPassFixedKey: 'mt2',
    },
  },
  idConnect: false,
  idConnectInfo: false,
  floodlight: false,
  facebook: false,
  track: true,
  fcTrack: true,
  idsync: false,
  utiq: true,
},

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close