DocumentationJourney OptimizerJourney Optimizer Guide

Configure your code-based experience code-based-configuration

Last update: Mon Oct 28 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Experienced
  • Admin

Before building your experience, you need to create a code-based experience configuration in which you define where the content will be delivered and consumed inside your application.

A code-based experience configuration must reference the surface, which is basically the location where you want to render your changes. According to the selected platform, you need to enter a location/path, or the full surface URI. Learn more

Create a code-based experience configuration create-code-based-configuration

To create a code-based experience channel configuration, follow these steps:

  1. Access the Channels > General settings > Channel configurations menu, then click Create channel configuration.

  2. Enter a name and a description (optional) for the configuration.

    note note
    NOTE
    Names must begin with a letter (A-Z). It can only contain alpha-numeric characters. You can also use underscore _, dot. and hyphen - characters.

  3. To assign custom or core data usage labels to the configuration, you can select Manage access. Learn more on Object Level Access Control (OLAC)

  4. Select Marketing action(s) to associate consent policies to the messages using this configuration. All consent policies associated with the marketing action are leveraged in order to respect the preferences of your customers. Learn more

  5. Select the Code-based experience channel.

  6. Select the platform for which the code-base experience will be applied:

    note note
    NOTE
    You can select several platforms. When choosing multiple platforms, the content is delivered to all the selected pages or apps.

  7. Choose the format expected by the application for this particular location. This will be used when authoring the code-based experience in campaings and journeys.

  8. Click Submit to save your changes.

You can now select this configuration when creating a code-based experience in your campaigns and journeys.

NOTE
Your app implementation team is responsible for making explicit API or SDK calls to fetch content for the surfaces defined in the selected code-based experience configuration. Learn more on the different customer implementations in this section.

Web platforms web

To define the code-based experience configuration settings for web platforms, follow the steps below.

  1. Select one of the following options:

    • Single page - If you want to apply the changes to a single page exclusively, enter a Page URL.

    • Pages matching rule - To target multiple URLs matching the same rule, build one or more rules. Learn more

      For example, if you want to edit elements that are displayed on all the women product pages of your Luma website, select Domain > Starts with > luma and Page > Contains > women.

  2. The following applies for the preview URL:

    • If a single page URL is entered, that URL will be used for the preview - no need to enter another URL.

    • If a pages matching rule is selected, you must enter a Default authoring and preview URL that will be used to preview the experience in the browser. Learn more

  3. The Location on page field specifies the exact destination inside the page you want users to access. It can be a particular section on a page within the site’s navigation structure, such as ‘hero-banner’ or ‘product-rail’.

Mobile platforms (iOS and Android) mobile

To define the code-based experience configuration settings for mobile platforms, follow the steps below.

  1. Enter your App id. This allows for accurate identification and configuration within the app’s operational environment, and ensures seamless integration and functionality.

  2. Provide the Location or path inside the app. This field specifies the exact destination within the app you want users to access. It can be a particular section or page deep within the app’s navigation structure, such as ‘hero-banner’ or ‘product-rail’.

  3. Fill in the Preview URL field to enable on-device previews. This URL informs the preview service of the specific URL to use when triggering preview on device. Learn more

    The preview URL is a deep link configured by the app developer within your app. This ensures that any URLs matching the deep link scheme will open within the app instead of in a mobile web browser. Contact your app developer to obtain the deep link scheme configured for your app.

    accordion
    The following resources can assist you in configuring deep links for your app implementation
    note note
    NOTE
    If you encounter issues while previewing the experience, please refer to this documentation.

Other platforms other

To define the code-based experience configuration settings for other platforms (such as video consoles, TV connected devices, smart TVs, kiosks, ATMs, voice assistants, IoT devices, etc.), follow the steps below.

  1. Select Other as the platform if your implementation is not for Web, iOS or Android, or if you need to target specific URIs.

  2. Enter the Surface URI. A surface URI is a unique identifier corresponding to the entity where you want to deliver your experience. Learn more

    note caution
    CAUTION
    Make sure you enter a surface URI that matches the one used in your own implementation. Otherwise, the changes cannot be delivered.

  3. Add another surface URI if needed. You can add up to 10 URIs.

    note note
    NOTE
    When adding multiple URIs, the content is delivered to all the listed components.

What is a surface? surface-definition

A code-based experience surface is any entity designed for user or system interaction, which is uniquely identified by an URI. The surface is specified in the application implementation and must match the surface referenced in your code-based experience channel configuration.

A surface can be seen as a container at any level of hierarchy with an entity (touchpoint) that exists.

  • It can be a web page, a mobile app, a desktop app, a specific content location within a larger entity (for example a div), or a non-standard display pattern (for example, a kiosk or a desktop app banner).

  • It can also extend to specific pieces of content containers for non-display or abstracted-display purposes (for example, JSON blobs delivered to services).

  • It can also be a wildcard surface that matches a variety of client-surface definitions (for example, a hero image location on every page of your website could translate in a surface URI like: web://mydomain.com/*#hero_image).

When creating a code-based experience channel configuration, you have two ways to specify the surface according to the selected platform:

  • For Web, iOS and Android platforms, you need to the enter a location or path to compose the surface.

  • If the platform is Other, you need to enter the full surface URI, like in the examples below.

A surface URI serves as a precise identifier directing to distinct user interface elements or components within an application. Basically, a surface URI is composed of multiple sections:

  1. Type: web, mobileapp, atm, kiosk, tvcd, service, etc.
  2. Property: page URL or app bundle
  3. Container: location on the page/app activity

The tables below list some surface URI definition examples for various devices.

Web and mobile

Type
URI
Description
Web
web://domain.com/path/page.html#element
Represents an individual element within a specific page of a specific domain, where an element can be a label like in the following examples: hero_banner, top_nav, menu, footer, etc.
iOS app
mobileapp://com.vendor.bundle/activity#element
Represents a specific element within a native app activity, such as a button or other view element.
Android app
mobileapp://com.vendor.bundle/#element
Represents a specific element within a native app.

Other device types

Type
URI
Description
Desktop
desktop://com.vendor.bundle/#element
Represents a specific element within an application, such as a button, menu, hero banner, etc.
TV app
tvcd://com.vendor.bundle/#element
Represents a specific element within a smart TV or TV connected device app - bundle ID.
Service
service://servicename/#element
Represents a server-side process or other manual entity.
Kiosk
kiosk://location/screen#element
Example of potential additional surface types that can be added easily.
ATM
atm://location/screen#element
Example of potential additional surface types that can be added easily.

Wildcard surfaces

Type
URI
Description
Wildcard web
wildcard:web://domain.com/*#element
Wildcard surface - represents an individual element in each of the pages under a specific domain.
Wildcard web
wildcard:web://*domain.com/*#element
Wildcard surface - represents an individual element in each of the pages under all domains that end with “domain.com”.
recommendation-more-help
b22c9c5d-9208-48f4-b874-1cefb8df4d76