Parameters and Callbacks

The parameters and callbacks outlined in the article below are typically set in the integration file that maps the logic of the PDP (product detail page on the client's website) to the logic of the Tangiblee platform - this file is typically named tangiblee-mapper.js.

For tangiblee-mapper.js to work properly, the Tangiblee API script tag should be included on the webpage. All the parameters and callbacks in this article rely on having the Tangiblee API script available and loaded.

Here is an example of how to include Tangiblee API script so it's methods will be available to use in the tangiblee-mapper.js:

<script async src="https://cdn.tangiblee.com/integration/3.1/tangiblee.min.js"></script>

[.bad]IMPORTANT: Tangiblee API script is occasionally updated with newer versions, if you're using Semi-managed or Self-service integration, make sure you use the latest version of Tangiblee API script. Ask your account manager if you're not sure.[.bad]

Clients using Managed Integration (one line Tag that wraps the tangiblee-mapper.js) do not need to worry about Tangiblee API script or any of the parameters and callbacks in this article, the Tangiblee team maintains the tangiblee-mapper.js for you bundled together with the Tangiblee API script (tangiblee.min.js) into a single tangiblee-bundle.min.js file.

If you're using Semi-Managed integration then the Tangiblee team will make sure to include Tangiblee API script tag and the tangiblee-mapper.js. If Tangiblee API script is updated, the Tangiblee team will reach out with details about the new version, and release notes.

Finally, for Self-Service integration, where you implement your own tangiblee-mapper.js, make sure to include the latest version of Tangiblee API script in your PDP, ask your account manager for details if you're not sure about its path.

SKUs and Catalog

startOnSKUs (skus:array)

startOnSKUs is the most important parameter on the document.

[.bad]Mandatory: This parameter must be set for Tangiblee integration to work.[.bad]

This parameter is first, but it's recommended to add it last on the integration script to ensure that all other Tangiblee parameters are set by the time it's called. This parameter passes the SKU IDs which are available on the PDP to Tangiblee API script.

Each time the startOnSKUs parameter is set, the Tangiblee API script validates that the SKUs exist and are ready on the Tangiblee platform.

This is done by an HTTP GET request to https://api.tangiblee.com; below is an example:

https://api.tangiblee.com/api/tngimpr?ids=GREEN_PRODUCT_SKU,WHITE_PRODUCT_SKU,LIME_PRODUCT_SKU&domain=www.example.com&locale=en-US

When Tangiblee API script receives the HTTP GET response it fires onSKUsValidated() event. After receiving the HTTP GET response Tangiblee API script is ready to determine which SKU is now active and should be displayed in Tangiblee UX.

In a simple case when there is only one SKU on a PDP, the startOnSKUs() is set to only one SKU which is active by default. In this case, there is no need to explicitly set activeSKU().

If there are multiple SKUs on the PDP, then startOnSKUs() should be set to an array of all the SKUs currently available on the PDP. activeSKU() then should be set and defines which SKUs on the array should be selected by default.

That's why it is important to always set the activeSKU() before startOnSKUs() in case there are multiple SKUs available on the PDP.

The list of SKUs set on startOnSKUs() should contain the SKU set as activeSKU(), for example:

tangiblee('activeSKU', 'WHITE_PRODUCT_SKU');
tangiblee('startOnSKUs', ['GREEN_PRODUCT_SKU', 'WHITE_PRODUCT_SKU', 'LIME_PRODUCT_SKU']);

[.good]In the example above Tangiblee API script will send HTTP GET request with 3 SKUs provided and when the response arrives the 'WHITE_PRODUCT_SKU' product will be chosen to be displayed inside Tangiblee UX.[.good]

[.good]This will occur only if 'WHITE_PRODUCT_SKU' has been Approved by Tangiblee, otherwise hideCTA() callback function will be called.[.good]

The example below shows how to configure Tangiblee API script with a product which is selected by default when the PDP is loaded. When a user changes the active product on a PDP then there is no need to set startOnSKUs() again if the new active SKU is in the list from the previous startOnSKUs() statement.

It's enough to simply set a new active SKU by setting activeSKU() again, i.e.:

// PDP loaded, 'WHITE_PRODUCT_SKU' is a default SKU
tangiblee('activeSKU', 'WHITE_PRODUCT_SKU');

// Tangiblee API script configured to use following SKUs available on the PDP:
tangiblee('startOnSKUs', ['GREEN_PRODUCT_SKU', 'WHITE_PRODUCT_SKU', 'LIME_PRODUCT_SKU']);
...
// In a while, the user changes the color of the active product on the PDP, for example, to 'LIME_PRODUCT_SKU'.
// Tangiblee API script is configured to display new active SKU in Tangiblee UX:
tangiblee('activeSKU', 'LIME_PRODUCT_SKU');

If active SKU is Approved by Tangiblee then the following actions will be made:

1. showCTA() callback function is called.
2. onCTAShown() event is fired when CTA is shown.

If the PDP is a Single-Page Application (SPA) then startOnSKUs() should be set each time the available list of PDP SKUs changes. The same applies to the activeSKU() - it should be set every time when the active SKU is updated. Both startOnSKUs() and activeSKU() can be called as many times as it's needed.

‍

Important Notes for using parameters and callbacks on SPAs:

• activeSKU() should be set before startOnSKUs() every time when startOnSKUs() is set to new list of SKUs. Then activeSKU() may be set as many times as needed until it is set to one of the SKUs from the list defined by the last startOnSKUs() statement. 
• startOnSKUs() will perform the HTTP GET request and will wait for the response. It should not be set often in a short period of time.‍

domain(domain:string)

[.bad]Mandatory: This parameter must be implemented for Tangiblee integration to work.[.bad]

Sets the domain for all API requests to the Tangiblee platform.

The combination of the domain param with the SKUs array (set as param startOnSKUs()) is a unique identifier for SKUs on Tangiblee's platform. This identifier is used to:

• Validate which SKUs are actually available on the Tangiblee platform to show on the PDP.
• Pull the configuration of Tangiblee UX for the specific SKU.
• Compose the Tangiblee iframe URL for the specific SKU.
• Collect analytics, usage, and e-commerce performance data.

[.good]Reminder: every request to Tangiblee servers uses domain + SKU ID as a unique identifier to a SKU in the client's catalog.[.good]

tangiblee('domain', 'www.tangiblee-integration.com');

‍

Privacy

useCookies (useCookies:bool)

‍

Determines if cookies can be used by Tangiblee UX.

If useCookies set to FALSE then:

• Google Analytics will not collect any data.
• Tangiblee will not save any user data between PDP visits, i.e. Tangiblee History feature will not be available.

tangiblee('useCookies', false);

iframe Placement

container (container:string)

‍

Determines if Tangiblee iframe should be displayed in a Tangiblee popup or in any other modal window/embedded directly to a given element on a PDP.

By default, Tangiblee iframe is placed in a .tangiblee-modal-iframe-container element. Tangiblee modal window will not be created if any other CSS selector is set.

// in this example the Tangiblee modal dialog will not be created
// and Tangiblee UX will be placed inside #tangiblee_app element
tangiblee('container', '#tangiblee_app');

‍

CTA (call-to-action) Callbacks

showCTA (showCTA:function)

‍

[.bad]Mandatory: This parameter must be implemented for Tangiblee integration to work.[.bad]

Defines how Tangiblee CTA (or CTAs) should look, both in terms of visuals (image, text, etc') and in terms of placement on the PDP.

The CTA (or CTAs) may already exist in the HTML (e.g. a placeholder) code and hidden by default, if that is the case, then showCTA defines actions needed to make CTA visible.

Returns

var showCTA = function(activeSKU, thumbUrl) {
     var ctaCssClass = 'tangiblee-cta',
         cta = document.getElementsByClassName(ctaCssClass)[0];
     if (cta) {
         cta.style.display = 'block';
     } else {
         var cta = document.createElement('button');
         cta.className = ctaCssClass;
         cta.innerText = 'Will it fit?';
         cta.style.backgroundImage = 'url(' + thumbUrl + ')';
         //...
         document.body.appendChild(cta);
     }
     return ctaCssClass;
};
tangiblee('showCTA', showCTA);

There may be any number of CTAs placed on the same PDP at the same time.

For example, there are 2 SKUs on a PDP: sku-black and sku-white. The PDP has 2 CTAs, one for each SKU, with black and white background respectively.

var showCTA = function(activeSKU, thumbUrl) {
    var ctaCssClass = 'tangiblee-cta',
        CTAs = document.querySelectorAll(ctaCssClass);
    if (CTAs.length) {
        for (var i = 0; i < CTAs.length; i++) {
            CTAs[i].style.display = 'block';
        }
    } else {
        var cta = document.createElement('button');
        cta.className = ctaCssClass + ' sku-black';
        cta.innerText = 'Will it fit?';
        cta.style.backgroundColor = 'black';
        //...
        document.body.appendChild(cta);
        var cta = document.createElement('button');
        cta.className = ctaCssClass + ' sku-white';
        cta.innerText = 'Will it fit?';
        cta.style.backgroundColor = 'white';
        //...
        document.body.appendChild(cta);
    }
    return ctaCssClass;
};

// Set active SKU depending on which CTA is clicked
var onCtaClicked = function(cta) {
    if (cta.className.indexOf('black') > -1) {
        tangiblee('activeSKU', 'sku-black');
    }
    if (cta.className.indexOf('white') > -1) {
        tangiblee('activeSKU', 'sku-white');
    }
}

tangiblee('showCTA', showCTA);
tangiblee('onCtaClicked', onCtaClicked);

‍

hideCTA (hideCTA:function)

Defines how Tangiblee CTA (or CTAs) should be removed from PDP.

This callback function can be omitted if there is only one SKU on a PDP and Tangiblee's CTA placement doesn't change when a user interacts with PDP (e.g. clicking drop-downs, color variations, etc`). If the CTA(s) should be created on the client-side via JavaScript code then this is the function that should remove the Tangiblee CTA correctly. Active SKU passed to the function as a first parameter.

var hideCTA = function(activeSKU) {
     var cta = document.getElementsByClassName('tangiblee-cta')[0];
     if (cta) {
         cta.parentNode.removeChild(cta);
     }
};
tangiblee('hideCTA', hideCTA);

‍

UX Customization

widgetVersion (widgetVersion:string)

‍

Sets a version of Tangiblee UX, and determines the version of UX loaded when Tangiblee is shown.

[.good]NOTE: v3 is the most updated version of Tangiblee UX and is the recommended value for this parameter[.good]

tangiblee('widgetVersion', 'v3');

‍

Syncing PDP changes with Tangiblee UX 

activeSKU (activeSKU:string)

‍

Useful when there is more than one SKU on the PDP that is approved by Tangiblee.

This parameter can be omitted if there is only one SKU on the PDP. Please refer to startOnSKUs() documentation section for more details about using startOnSKUs() and activeSKU() together.

It should be set each time when an active SKU is changed on the PDP.

tangiblee('activeSKU', 'WHITE_PRODUCT_SKU');

‍

activeLocale (activeLocale:string)

This parameter sets the active document activeLocale. Used to identify a localized version of the SKU if there is more then one activeLocale configured for the Client's website.

document.documentElement.lang used by default.

It should be set each time when the active locale is changed on the PDP. 

tangiblee('activeLocale', 'en-US');

‍

activePrice (activePrice:string)

Sets the price of the SKU in Tangiblee UX.

It should be set each time when the price of active SKU is changed on the PDP.

tangiblee('activePrice', '42');

‍

activeCurrency (activeCurrency:string)

Sets the active currency used in Tangiblee UX.

It should be set each time when the currency of active SKU is changed on the PDP.

tangiblee('activeCurrency', '$');

‍

activeATC (activeATC:string)

Sets the active add-to-cart (ATC) selector in the PDP. If ATC button is visible in Tangiblee UX then clicking that ATC will trigger the selector set as activeATC.

It should be set each time when the add-to-cart (ATC) selector of active SKU is changed on the PDP.

tangiblee('activeATC', '.btn-cart');

‍

Google Analytics Integration (GA Integration)

Self-Service, Semi-Managed and Managed Integration tags contain only generic Tangiblee Analytics API code inside it, but not the Tangiblee Analytics mapping code. Generic Tangiblee Analytics API code allows tracking common parameters like Pageviews. Tangiblee Analytics mapping code should be created to do Order Tracking. It typically contains the code needed to send the order data to the Analytics system.

Tangiblee Analytics mapping code should be added to the relevant pages (Thank You Page, Order Review Page, etc) using the separate Tangiblee Analytics tag.

Please refer to the Collecting Tangiblee Performance Metrics section for more details on how to add Tangiblee Analytics tag to the webpages and set it up.