Customizing UTM (Tracking) Codes

How can we customize Tracking Codes (UTM Codes)?

Each product being ordered as part of the campaign, accepts a utm parameter under orderedProductsSpecs, as can be seen on HAPI Backend Documentation. By default, as part of the UTM Codes Step of the Order Journey, we apply the following UTM codes to each of the product/contract:

• utmCampaign -> jobmarketing
• utmMedium -> jobposting
• utmSource -> Name of the Channel of Product/Contract

There are two ways to override these codes:

Overriding all product/contract tracking codes in one batch

console.log('UTM Default Settings', window.hapi.orderJourney.state.utmCodesStepData.value.settings)
// Outputs:
/*
[
    {
        "mapToName": false,
        "value": "jobmarketing",
        "key": "utmCampaign"
    },
    {
        "mapToName": false,
        "value": "jobposting",
        "key": "utmMedium"
    },
    {
        "mapToName": true,
        "value": "",
        "key": "utmSource"
    }
]
*/

mapToName: boolean, when passed as true, maps the value of the parameter to Channel's name. By overriding this array, you can set all of product/contracts tracking codes:

const ourTrackingCodes = [
    {
         "mapToName": false,
         "value": "someCustomParameterValueOne",
         "key": "someCustomParameterNameOne"
    },
    {
         "mapToName": false,
         "value": "someCustomParameterValueTwo",
         "key": "someCustomParameterNameTwo"
    },
    {
         "mapToName": true,
         "value": "",
         "key": "customCustomParameterMappedToNameOfChannel"
    }
]

window.hapi.orderJourney.state.utmCodesStepData = {
    ...window.hapi.orderJourney.state.utmCodesStepData.value,
    settings: ourTrackingCodes
}

This will re-generate all of per product/contract tracking codes. If needed, you can further customize each product/contract's tracking codes by further adding/removing/customizing them. Refer to Overriding tracking codes per product/contract section for more info.

Overriding tracking codes per product/contract

By default, product/contract tracking codes equal to the tracking codes in the settings array, meaning that the value of this will be empty:

console.log('Product UTMs', window.hapi.orderJourney.state.utmCodesStepData.value.productUTMs)

To customize tracking codes per product/contract, you need to construct the tracking codes of that product/contract yourself:

const ourBaseTrackingCodes = [
    {
        "mapToName": false,
        "value": "someCustomParameterValueOne",
        "key": "someCustomParameterNameOne"
    },
    {
        "mapToName": false,
        "value": "someCustomParameterValueTwo",
        "key": "someCustomParameterNameTwo"
    },
    {
        "mapToName": true,
        "value": "",
        "key": "customCustomParameterMappedToNameOfChannel"
    }
]

const basketProducts = window.hapi.basket.state.products.value

const productUTMs = {}

basketProducts.forEach(basketProduct => {
    const basketProductId = window.hapi.basket.utils.getBasketProductId(basketProduct);

    const customUTMsForThisProduct = [...ourBaseTrackingCodes];

    if (basketProductId === '180') {
        customUTMsForThisProduct.push({
            "mapToName": false,
            "value": "customValueForThis",
            "key": "customNameForThis"
        })
    }

    // Alternatively you can also check the title of product/contract:
    /*
    const basketProductTitle = window.hapi.basket.utils.getBasketProductId(basketProduct);
    if (basketProductTitle.includes('Techniek Werkt')) {
        customUTMsForThisProduct.push({
            "mapToName": false,
            "value": "customValueForThis",
            "key": "customNameForThis"
        })
    }
    */

    productUTMs[basketProductId] = customUTMsForThisProduct
})