DocumentationJourney OptimizerJourney Optimizer Guide

Code-based experience surfaces code-based-surface

Last update: Mon Jun 02 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Experienced
  • Admin

What is a surface? surface-definition

A code-based experience surface is any entity designed for user or system interaction, 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).

NOTE
When you have multiple code-based experience actions running on the same surface, the campaign or journey’s Priority score determines what is delivered to the end-user if they qualify for more than one action. Learn more on priority scores

Surface identifier surface-uri

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”.

URI composition uri-composition

In Journey Optimizer, the code-based experience channel supports two types of customer implementations:

NOTE
Learn more about the implementation prerequisites in this section.

Using code-based experiences, you can modify content on granular locations which are uniquely identified by Journey Optimizer using surface URIs.

These surface URIs are composed and handled depending on the implementation method:

  • Web/Mobile SDK: Your web/mobile developer needs to define these granular locations as simple strings, because the Web/Mobile SDK is capable of automatically compose the surface URI based on the current URL/app ID and the location string.

  • Edge Network APIs: The app/page developer must define full surface URIs that include the full path and location where the content will be consumed, because the full URIs are required in this type of implementation.

This is why, 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 the URL/app ID and a location or path to compose the surface. Learn more about configuring code-based experiences for web and mobile platforms

  • If the platform is Other, you need to enter the full surface URI, like in the examples above. Learn more about configuring code-based experiences for other platforms

recommendation-more-help
b22c9c5d-9208-48f4-b874-1cefb8df4d76