# Personalization event

Often, when choosing a personalization option, complex JavaScript logic needs to be executed. This can be achieved by subscribing to the personalization event.

# General Idea

Subscription is a special method call within JavaScript code. You can subscribe to either a personalization or a combination of personalization and personalization option.

The result of subscribing is the execution of custom code inside the handler.

The simplest subscription looks like this:

// Show the best review for the product
impact('onPersonalization', {
personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',

    // called when personalization is applied
    handler: (personalization, personalizationOption, dataContext) => {
      switch (personalizationOption.id){
        case ("10337247-6fa7-4ac3-92ed-bb2506d79ffa"):
          // Да
          break;
        case ("fb8211d7-5aa3-40df-a3ed-54a67d72f850"):
          // Нет
          break;
        default:
          // ...
      }
    },
})

# Types of subscription

There are three main types of subscription:

# Only personalization (Id is specified).

In this case, the subscription will be triggered whenever any personalization is applied, regardless of the personalization option.

Effectively, this means the subscription will be triggered whenever the personalization is applicable based on display conditions.

Example:

// Show the best review for the product
impact('onPersonalization', {
personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',

    handler: (personalization, personalizationOption) => {
      switch (personalizationOption.id){
        // called for any option of personalization
      }
    },
})

# Both personalizationId + personalizationOptionId (personalization ID or и personalization option ID) are specified.

In this case, the subscription will be triggered only when the specified personalization option is applied.

Example:

// Show the best review for the product -> Yes
impact('onPersonalization', {
    personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',
    personalizationOptionId: '10337247-6fa7-4ac3-92ed-bb2506d79ffa',

    handler: (personalization, personalizationOption) => {
        // Triggered if the personalization option Show the best review for the product is selected = Yes
    },

})

# Neither personalizationId nor personalizationOptionId is specified

In this case, the subscription will be triggered for every applied personalization on the current page.

This type of subscription can be useful for client-side infrastructure tasks, for example, if you want to add all applied personalizations to a custom analytics system.

Example:

impact('onPersonalization', {

    handler: (personalization, personalizationOption) => {
        // Called for every applied personalization
    },
})

# Timeout

In some cases, personalization is critical in terms of execution time.

For example, if there are two landing page options and an intermediate page with personalization that redirects the user to the appropriate landing page option based on the selected personalization result.

In this case, if:

The request to fetch personalizations from the server "fails"
The request to fetch personalizations from the server "did not have time to execute"

Within the specified timeout in the handler, another special handler onTimeoutExceeded is called.

Example:

// Show the best review for the product
impact('onPersonalization', {
personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',

    // Main personalization handler
    handler: (personalization, personalizationOption) => {
        // ...
    },

    // how many milliseconds to wait for personalizations to be applied
    timeout: 2000

    // called if the subscription does not apply within the specified time
    onTimeoutExceeded: (personalization, personalizationOption) => {
      // ...
    },
})

# Multiple subscriptions personalizationId + personalizationOptionId with timeout

If there are multiple subscriptions to different variants of the same personalization, and each subscription has a specified execution timeout, then upon successful execution of any of these subscriptions, the timeout will NOT be triggered in the others.

Example:

// Show the best review for the product -> No
impact('onPersonalization', {
    personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',
    personalizationOptionId: 'fb8211d7-5aa3-40df-a3ed-54a67d72f850',

    handler: (personalization, personalizationOption) => {
    },

    timeout: 1000

    onTimeoutExceeded: (personalization, personalizationOption) => {
        // Not triggered if Show the best review for the product -> Yes
        // Successfully "executed"
    },

})

// Show the best review for the product -> Yes
impact('onPersonalization', {
    personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',
    personalizationOptionId: '10337247-6fa7-4ac3-92ed-bb2506d79ffa',

    handler: (personalization, personalizationOption) => {
    },

    timeout: 1000

    onTimeoutExceeded: (personalization, personalizationOption) => {
        // Not triggered if Show the best review for the product -> No
        // Successfully executed
    },

})

# Default Timeout

By default, the timeout is set to 5 seconds. Therefore, if a subscription has onTimeoutExceeded but no specified timeout, the value of 5 seconds will be used.

Example:

impact('onPersonalization', {
    personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',
    personalizationOptionId: '10337247-6fa7-4ac3-92ed-bb2506d79ffa',

    handler: (personalization, personalizationOption) => {
    },

    onTimeoutExceeded: (personalization, personalizationOption) => {
        // Will be triggered after 5 seconds if the conditions for triggering the timeout are met
    },

})

# Subscription method returns a Promise

The onPersonalization method returns a Promise (opens new window).

This means you can use await to synchronously wait for the personalization result.

When using promises, wait for the script to be ready - window.SustainImpact.ready == true

This also allows you to perform some action asynchronously immediately after successful or unsuccessful retrieval of personalization.

Example:

// Default pickup point selection during checkout
impact('onPersonalization', {
personalizationId: 'e9b3f461-0857-4b21-a6fc-1bdcbe429cd4',

    // called when personalization is applied
    handler: (personalization, personalizationOption) => {
      switch (personalizationOption.id){
        case ("a554d770-3ed3-4d07-be0b-98475e27eb44"):
          // Нет
          break;
        case ("cc30da87-338c-49a2-adcc-f2c3b47ee6ed"):
          // Да
          break;
        default:
          // ...
      }
    },
}).then(({personalizationId, personalizationOptionId}) => {
    // After successful execution of the subscription
}, ({personalizationId, personalizationOptionId}) => {
    // After unsuccessful execution of the subscription
    // personalizationId and personalizationOptionId may not be filled!
})

# Third Argument in handler - dataContext

Inside the handler function, you have access to the current context through the dataContext variable.

Example:

impact('onPersonalization', {
    personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',
    personalizationOptionId: '10337247-6fa7-4ac3-92ed-bb2506d79ffa',
    handler: (personalization, personalizationOption, dataContext) => {
        
        if(dataContext){
            // Example of working with dataContext
            let cityName = dataContext.geo.city.nativeName;
            let population = dataContext.geo.city.population;
            let cityInfo = "You are in the city of " + cityName + ", which has a population of " + population + " people.";
            if (dataContext.geo.city.isRegionCapital) {
                cityInfo += "This city is the capital of the region.";
            }
            if (dataContext.geo.city.isCountryCapital) {
                cityInfo += "This city is the capital of the country.";
            }

            // The variable cityInfo will contain the string
            // You are in the city of Moscow, which has a population of 12,615,078 people. This city is the capital of the country.
        }
    },

})

# List of available fields in the data variable

Within the handler function, using the dataContext variable, you have access to the following context data:

geo.city.nativeName: City name in the native language.
geo.city.englishName: City name in English.
geo.city.russianName: City name in Russian.
geo.city.isRegionCapital: Indicates if the city is a regional capital.
geo.city.isCountryCapital: Indicates if the city is a country's capital.
geo.city.population: City population.
geo.region.nativeName: Region name in the native language.
geo.region.englishName: Region name in English.
geo.region.russianName: Region name in Russian.
geo.region.population: Region population.
geo.country.nativeName: Country name in the native language.
geo.country.englishName: Country name in English.
geo.country.russianName: Country name in Russian.
geo.country.population: Country population.
page.schemaOrg.brandName: Brand name in Schema.org format.
page.schemaOrg.offer.price: Offer price in Schema.org format.
page.schemaOrg.offer.availability: Offer availability in Schema.org format.
page.schemaOrg.aggregateRating.ratingValue: Rating value in Schema.org format.
page.schemaOrg.aggregateRating.reviewCount: Number of reviews in Schema.org format.
weather.temp: Current temperature.
weather.tempFeelsLike: Feels like temperature.
weather.humidity: Humidity.

# Deprecated subscription method

For backward compatibility, the deprecated method window.SustainImpact.onPersonalization is also available, which fully replicates the functionality described above.

Example:

window.SustainImpact.onPersonalization({
    personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',
    personalizationOptionId: '10337247-6fa7-4ac3-92ed-bb2506d79ffa',
    handler: (personalization, personalizationOption, dataContext) => {
        // Your handler code
    },

})

← Configuration Customer custom parameters →