DocumentationJourney OptimizerJourney Optimizer Guide

Get started with code-based channel get-sarted-code-based

Last update: Thu May 23 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Experienced
  • User
  • Developer
  • Admin

Journey Optimizer allows you to personalize and test the experiences you want to deliver to your customers across all your touchpoints like: web apps, mobile apps, desktop apps, video consoles, TV connected devices, smart TVs, kiosks, ATMs, voice assistants, IoT devices, etc.

With the code-based experience capability, you can define inbound experiences using a simple and intuitive non-visual editor. It allows you to insert and edit specific elements at individual and more granular locations of your apps or web pages, no matter the type of applications you have - rather than applying modifications to an entire content.

IMPORTANT
Specific guardrails and recommendations for code-based experiences are detailed in this page.

Lead

How it works

Validation

Guardrails and prerequisites

Infrequent

Create a code-based experience

Validation

Implementation samples

When to use code-based vs. other channels code-based-vs-other-channels

Code-based vs. other channels

When to use the code-based channel rather than the other Journey Optimizer channels?

  • You can consider using code-based experiences any time when your digital property is not accessed through a web browser or a mobile app – cases in which you can probably better use the Journey Optimizer web channel or the Journey Optimizer in-app messaging channel.

  • You can use the code-based channel as an alternative to the Journey Optimizer web channel if your website cannot be loaded into the web designer visual editor or if you cannot use the browser extension that powers visual authoring for web channel.

  • You can also use the code-based channel as an alternative to the Journey Optimizer web or in-app channels in case you have an API-based, headless or server-side implementation.

Code-based vs. web channel

To execute web use cases, you can use either the web channel or code-based experience, but depending on your context one would be more appropriate than the other. The main differences are listed below so you can make an informed decision on what to use when.

Web

Code-based experience

  • Edit your content using the personalization editor.
  • The code-based experience requires previous development work on your implementation to make sure that your surfaces can interpret and deliver the content published on the edge by Journey Optimizer for these surfaces. Learn more
  • It requires more planning and it can change only the things that developers specify. Therefore, it is essential to identify the components (home banner, hero image, menu bar, etc.) on the surfaces that need to be modified for personalization or testing, and work with your development team to build the implementation needed for handling these changes.
  • It allows you to use JSON code content.
  • It is developer-persona focused.

How it works how-it-works

CAUTION
This feature is for developer persona and/or experienced users. It can be used by marketers with some code-writing skills, as long as the surface implementations and initial setup are handled by the your development team.

To edit your content using the Journey Optimizer code-based experience feature, your pages or apps need to be instrumented. To do so, you must declare upfront the specific individual locations (called “surfaces”) where you want to insert or replace content.

NOTE
Currently the content associated with a surface can only be HTML or JSON.

The key steps to implement a code-based campaign are as follows.

  1. Define a surface, which is basically the location where you want to add your code-based experience, and create a campaign in Journey Optimizer using this surface. Learn how

  2. Compose an experience by specifying content for the selected surface using the Journey Optimizer personalization editor. Learn how

  3. Your app implementation team makes explicit API or SDK calls to fetch content for the named surfaces, such as “Banner Text” or “Recommendations Tray 1”, or non-UI-related decision points in an application, such as “search algorithm parameters”. In this case, the implementation team is responsible for rendering or otherwise interpreting and acting on the returned content.

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.

In other words, 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).

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