# developer Salesforce Personalization (einstein-personalization) - Full Documentation

<!-- document id=2fb96b4bfb4d09e9146b82c72369e106a0957c2ecb9829aea8ac4cf374740800 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/mobile-integration/configure-mobile-personalization/personalize-mobile-experiences-android.md -->

# Android Integration

Configure the Android app to identify users and manage consent settings, enabling you to request and display content tailored to specific user interactions.

1. [Install the SDK](#install-the-sdk)
2. [Initialize the Data 360 and Personalization Modules](#initialize-the-data-360-and-personalization-modules)
3. [Request Personalization](#request-personalization)
4. [Access Responses](#access-responses)
5. [Error Handling](#error-handling)

## Install the SDK

Integrate the Personalization module into your Android project by updating your Gradle configuration files.

1. Update the Personalization repository in your module-level `build.gradle` file.

```kotlin
repositories {
  maven {
    url "https://salesforce-marketingcloud.github.io/MarketingCloudSDK-Android/repository"
  }
  maven {
    url "https://salesforce-marketingcloud.github.io/mobile-sdk-cdp-android/repository"
  }
  maven {
    url "https://salesforce-marketingcloud.github.io/Personalization-Android/repository"
  }
}
```

2. Add the SDK dependencies to your app's `build.gradle` file.

```kotlin
dependencies {
    // Personalization SDK (includes SFMC SDK and CDP SDK dependencies)
    implementation 'com.salesforce.personalization:sdk:3.+'
}
```

## Initialize the Data 360 and Personalization Modules

The host app owns SDK initialization. Initialize both the [Data 360 module](https://developer.salesforce.com/docs/data/data-cloud-engagement-mobile-sdk/guide/c360a-api-engagement-mobile-sdk-initialization.html) and the Personalization module in your `Application.onCreate()`, before making any `fetchDecisions` calls.

```kotlin
import com.salesforce.marketingcloud.cdp.CdpConfig
import com.salesforce.marketingcloud.sfmcsdk.SFMCSdk
import com.salesforce.marketingcloud.sfmcsdk.SFMCSdkModuleConfig
import com.salesforce.personalization.PersonalizationConfig

/* Initialization of the CDP module for data collection */
val flushRate = EventFlushRate.Quantity(quantity = 1)
val cdpConfig = CdpConfig.Builder(
    context = this,
    appId = "<Your CDP App ID>", // Your CDP Mobile Connector app ID
    endpoint = "<Your CDP Endpoint>" // Your CDP Mobile Connector endpoint
).eventFlushRate(flushRate)
 .build()

/* Initialization of the personalization module with needed configuration */
val personalizationConfig = PersonalizationConfig.Builder(this)
    // Optionally define your dataspace. The "default" data space is used if you don't explicitly provide one.
    .dataspace("myDataspaceApiName")
    .build()

/* The CDP and Personalization configurations initialized above are provided to SFMCSdk.configure */
SFMCSdk.configure(this, SFMCSdkModuleConfig.build {
    cdpModuleConfig = cdpConfig
    personalizationModuleConfig = personalizationConfig
})
{ initStatus ->
    Log.d(TAG, "SDK initialized: ${initStatus.status}")
}
```

**note:** In your production application, you must explicitly manage user consent using the solution provided in the Engagement Mobile SDK. See [Data 360 Consent Management](https://developer.salesforce.com/docs/data/data-cloud-engagement-mobile-sdk/guide/c360a-api-engagement-mobile-sdk-consent-management.html).

### Considerations

- Call this initialization once, from `Application.onCreate()` - not from an `Activity` or `Fragment` - so the SDK is ready before any screen requests decisions.
- Use the same context instance (`this`, referring to the `Application`) for both `CdpConfig.Builder` and `PersonalizationConfig.Builder`.
- The system uses the `default` data space if you don't explicitly provide one.
- To enable debug logging during development, add this snippet before `SFMCSdk.configure(...)`, so logging is active for the whole init sequence. Make sure this setting is disabled or removed before building your application for production.

  ```kotlin
  SFMCSdk.setLogging(DEBUG, AndroidLogger())
  ```

  For more information on logging, see [Logging and Debugging](https://developer.salesforce.com/docs/data/data-cloud-engagement-mobile-sdk/guide/c360a-api-engagement-mobile-sdk-logging-and-debugging.html).

## Request Personalization

The `fetchDecisions` method enables you to interact with the Decisioning API and request one or more personalizations for specific areas of your mobile application. The SDK provides two methods for fetching personalization decisions: suspend functions (recommended) and callbacks.

### Use a Suspend Function to Fetch Decisions (Recommended, Kotlin Only)

Call `fetchDecisions` within a coroutine scope to handle personalization requests asynchronously.

```kotlin
import com.salesforce.personalization.PersonalizationSdk
import com.salesforce.personalization.errors.PersonalizationException
import com.salesforce.personalization.http.DecisionsRequestContext
import com.salesforce.personalization.http.DecisionsResponse
import com.salesforce.personalization.utils.Result

// In a coroutine scope (ViewModel, LaunchedEffect, and so on.)
val result = PersonalizationSdk.fetchDecisions(
    personalizationPointNames = listOf("point1", "point2"),
    // Optionally use additional context to influence the decisions.
    // See "Request Personalization By Using Context" for details.
    decisionsRequestContext = decisionsRequestContext, // Optional
    timeoutMs = 10000L // Optional: 10 seconds (default: 10s)
)

when (result) {
    is Result.Success -> {
        // Handle successful response
        val response: DecisionsResponse = result.output
        // Process personalizations...
    }
    is Result.Failure -> {
        // Handle error
        val exception: PersonalizationException = result.throwable
        Log.e(TAG, "Personalization failed: ${exception.message}")
    }
}
```

| Parameter                 | Description                                                                                                                                                                    |
| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| personalizationPointNames | A list of at least one personalization point API Name (not the display label) for which you want to return decisions.                                                          |
| decisionsRequestContext   | (Optional) Additional context information. See [Request Personalization By Using Context](#request-personalization-by-using-context). If you don't have any context, pass nil. |
| timeoutMs                 | (Optional) The duration, in seconds, before the fetch task times out. The default is 10 seconds.                                                                               |

**note:** Grouping personalization point names by datagraph is the responsibility of the caller. This method does not automatically group or separate requests based on datagraph configuration. See [Request Personalization](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/decisioning-api-request-personalization.html#body).

### Use a Callback to Fetch Decisions

If your architecture does not support coroutines, use the callback-based implementation of `fetchDecisions` to handle responses.

```kotlin
import com.salesforce.personalization.PersonalizationSdk
import com.salesforce.personalization.errors.PersonalizationException
import com.salesforce.personalization.http.DecisionsRequestContext
import com.salesforce.personalization.http.DecisionsResponse
import com.salesforce.personalization.utils.Result

PersonalizationSdk.fetchDecisions(
    scope = lifecycleScope, // or viewModelScope, rememberCoroutineScope(), and so on.
    personalizationPointNames = listOf("point1", "point2"),
    // Optionally use additional context to influence the decisions.
    // See "Request Personalization By Using Context" for details.
    decisionsRequestContext = decisionsRequestContext,
    timeoutMs = 10000L, // Optional: 10 seconds (default: 10s)
    callbackDispatcher = Dispatchers.Main, // Optional dispatcher for callback. (Defaults to Dispatchers.Main.)
    callback = { result ->
        when (result) {
            is Result.Success -> {
                // Handle successful response
                val response: DecisionsResponse = result.output
                // Process personalizations...
            }
            is Result.Failure -> {
                // Handle error
                val exception: PersonalizationException = result.throwable
                Log.e(TAG, "Personalization failed: ${exception.message}")
            }
        }
    }
)
```

| Parameter                 | Description                                                                                                                                                                                       |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| personalizationPointNames | A list of at least one personalization point API Name (not the display label) for which you want to return decisions.                                                                             |
| context                   | (Optional) Additional context information. See [Request Personalization By Using Context](#request-personalization-by-using-context). If you don't have any context, pass nil.                    |
| timeoutMs                 | (Optional) The duration, in seconds, before the fetch task times out. The default is 10 seconds.                                                                                                  |
| callbackDispatcher        | (Optional) The dispatcher for callback. The default is `Dispatchers.Main`.                                                                                                                        |
| callback                  | Function that executes when the fetch operation completes. The callback receives a `Result` object containing either a `DecisionsResponse` on success or a `PersonalizationException` on failure. |

**note:** Grouping personalization point names by datagraph is the responsibility of the caller. This method does not automatically group or separate requests based on datagraph configuration. See [Request Personalization](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/decisioning-api-request-personalization.html#body).

### Request Personalization By Using Context

You can use additional context to influence personalization decisions. Use this method only if you have specific context available to affect the decisions. To know about context variables and how they can be used, see [Filter Recommendations Using Dynamic Context Variables](https://help.salesforce.com/s/articleView?id=mktg.persnl_recommender_filter_using_dynamic_variable.htm).

Construct a `DecisionsRequestContext` object and use the required context.

```kotlin
import com.salesforce.personalization.http.DecisionsRequestContext

/* Optionally use a request context */
val decisionsRequestContext = DecisionsRequestContext.Builder()
    // Optionally define the anchor item for your recommendations
    .anchorId("PRODUCT_123")

    // Optionally define type of an anchor item
    .anchorDmoName("ssot__GoodsProduct__dlm")

    // Optionally define the contextual attributes and their values
    .contextualAttribute(name: "category", value: "shoes")
    .contextualAttribute(name: "color", value: "red")

    .build()
```

For the `DecisionsRequestContext` builder, optionally add the following fields.

| Optional Field        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `anchorID`            | The unique identifier of the specific item the user is currently viewing. This is helpful in context-aware strategies, such as "People who bought this item also bought…"                                                                                                                                                                                                                                                                       |
| `anchorDmoName`       | The API Name of the DMO that corresponds to the anchorId. This tells the system what kind of item the anchor is. The DMO name should correspond to the actual one set up in Data 360. Example: `ssot__GoodsProduct__dlm`. If omitted, the system infers the anchor type from `anchorId` automatically.                                                                                                                                          |
| `contextualAttribute` | Run-time attributes that help refine recommendation responses and enable advanced filtering logic in your recommenders. To pass multiple attributes, you need to chain a separate method call for each specific key-value pair. For information on contextual attributes, see [Filter Recommendations Using Dynamic Context Variables](https://help.salesforce.com/s/articleView?id=mktg.persnl_recommender_filter_using_dynamic_variable.htm). |

The `fetchDecisions` method interacts with the Decisioning API and requests one or more personalizations for specific areas of your mobile application.

```kotlin
import com.salesforce.personalization.PersonalizationSdk
import com.salesforce.personalization.http.DecisionsRequestContext

// In a coroutine scope (suspend function)
val result = PersonalizationSdk.fetchDecisions(
    personalizationPointNames = listOf("Hero_Banner", "Footer_Promo"),
    decisionsRequestContext = decisionsRequestContext
    // Applies to ALL personalization points above
)
```

## Access Responses

The `fetchDecisions` method returns a `DecisionsResponse` object. This object contains both the raw list of personalizations and an optimized dictionary lookup.

### `DecisionsResponse` Structure

| Field                  | Type                                            | Description                                                                                                       |
| :--------------------- | :---------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
| requestId              | String                                          | The unique identifier associated with the underlying network request, useful for diagnostics.                     |
| personalizations       | `List<DecisionsResponsePersonalization>`        | A list of all personalization objects returned.                                                                   |
| personalizationsByName | `Map<String, DecisionsResponsePersonalization>` | A dictionary of personalization points indexed by name. We recommend this instead of a list for efficient access. |

### `DecisionsResponsePersonalization` Structure

Each item in the `personalizations` list (accessible via `personalizationsByName`) represents the content returned for a specific personalization point:

| Field                    | Type                                   | Description                                                                                                                        |
| :----------------------- | :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| `personalizationId`      | String                                 | The unique ID of the personalization.                                                                                              |
| personalizationPointName | String                                 | The name of the personalization point requested.                                                                                   |
| `personalizationPointId` | String                                 | The ID of the personalization point.                                                                                               |
| attributes               | Map\<String, JsonElement\>             | Mapped JSON object of attributes (metadata) returned for this personalization. The schema is defined by the personalization setup. |
| data                     | List\<DecisionsResponseContentObject\> | The JSON object with content items (the actual personalized content).                                                              |
| decisionId               | String?                                | (Optional) The unique identifier for the specific decision made by the server.                                                     |

### Example to Access Response Content

```kotlin
import com.salesforce.personalization.http.DecisionsResponse
import com.salesforce.personalization.http.DecisionsResponsePersonalization
import com.salesforce.personalization.http.DecisionsResponseContentObject

val response: DecisionsResponse = result.output

// Using lookup (preferred)
val homeHero = response.personalizationsByName["homeHero"]

if (homeHero != null) {
    // Access attributes
    // Safe string extraction
    val intro = homeHero.attributes["IntroductionText"]
        ?.takeIf { it is JsonPrimitive && it.isString }
        ?.let { (it as JsonPrimitive).content }

    // Safe number extraction
    val priority = homeHero.attributes["priority"]
        ?.takeIf { it is JsonPrimitive && it.isString }
        ?.let { (it as JsonPrimitive).content?.toIntOrNull() }

    // Access content objects
    homeHero.data.forEach { contentObj ->
        val contentId = contentObj.personalizationContentId

        val title = contentObj["title"]
            ?.takeIf { it is JsonPrimitive && it.isString }
            ?.let { (it as JsonPrimitive).content }
            ?: "Default Title"

        val imageUrl = contentObj["imageUrl"]
            ?.takeIf { it is JsonPrimitive && it.isString }
            ?.let { (it as JsonPrimitive).content }

        // Check if key exists
        if (contentObj.containsKey("description")) {
            val description = contentObj["description"]
                ?.takeIf { it is JsonPrimitive && it.isString }
                ?.let { (it as JsonPrimitive).content }
        }

        // Get all available keys
        val allKeys = contentObj.keys()
    }
}

// Iterate all personalizations
response.personalizations.forEach { personalization ->
    println("Point: ${personalization.personalizationPointName}")
    println("Items: ${personalization.data.size}")
}
```

In the example, `fetchDecisions` sends the user context to the server to request content for both `homeHero` and `product_recs` simultaneously. After the response arrives, `personalizationsByName` allows you to access the results for each point independently.

## Error Handling

Implement error handling for decision fetching. We recommend logging the exception.

```kotlin
import com.salesforce.personalization.PersonalizationSdk
import com.salesforce.personalization.errors.PersonalizationException
import com.salesforce.personalization.http.DecisionsResponse
import com.salesforce.personalization.utils.Result

// Simple Error Handling (Recommended)

val result = PersonalizationSdk.fetchDecisions(listOf(pointName))
when (result) {
    is Result.Success -> {
        // Handle success
        val response = result.output
        // Process personalizations...
    }
    is Result.Failure -> {
        // Log the error - no need to differentiate exception types for most use cases
        Log.e(TAG, "Personalization failed: ${result.throwable.message}", result.throwable)
    }
}

// Detailed Error Handling (Optional)

val result = PersonalizationSdk.fetchDecisions(listOf(pointName))
when (result) {
    is Result.Success -> {
        // Handle success
    }
    is Result.Failure -> {
        val exception = result.throwable

        // Optional: Differentiate by exception type if needed
        when (exception.type) {
            PersonalizationException.Type.TIMEOUT -> {
                Log.e(TAG, "Request timeout: ${exception.reason}")
                // Show retry option to user
            }
            PersonalizationException.Type.NETWORK -> {
                Log.e(TAG, "Network error: ${exception.reason}")
                // Show offline message
            }
            else -> {
                Log.e(TAG, "Personalization error: ${exception.message}")
            }
        }
    }
}
```

<!-- document id=e314b1c677511dec013ccd562c4e7e3b1ccddb38e1588b559da1472646a6c31e url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/mobile-integration/configure-mobile-personalization/personalize-mobile-experiences-lowcode-android.md -->

# Android Low-Code Integration

Use the LowCodeMobile Android SDK to display personalized content in your Android app with minimal setup. The SDK renders out-of-the-box Banner and Recommendations components and supports custom components for fully custom UI.

1. [Install the SDK](#install-the-sdk)
2. [Initialize the SDK](#initialize-the-sdk)
3. [Display a Content Zone](#display-a-content-zone)
4. [Out-of-the-Box Components](#out-of-the-box-components)
5. [Custom Components](#custom-components)
6. [Engagement Tracking](#engagement-tracking)
7. [Preview](#preview)
8. [Design-Time Rendering](#design-time-rendering)
9. [Error Handling](#error-handling)

## Install the SDK

Add the required Maven repositories to your project-level `settings.gradle.kts` (or `build.gradle`):

```kotlin
repositories {
  maven {
    url "https://salesforce-marketingcloud.github.io/MarketingCloudSDK-Android/repository"
  }
  maven {
    url "https://salesforce-marketingcloud.github.io/mobile-sdk-cdp-android/repository"
  }
  maven {
    url "https://salesforce-marketingcloud.github.io/Personalization-Android/repository"
  }
}
```

Add the LowCodeMobile dependencies to your app-level `build.gradle.kts`:

If you are using the out-of-the-box components (the SDK and lowcodemobile dependencies are pulled in automatically):

```kotlin
dependencies {
    implementation("com.salesforce.personalization:ootbcomponents:1.+")
}
```

If you are not using the out-of-the-box components (the SDK dependency is pulled in automatically):

```kotlin
dependencies {
    implementation("com.salesforce.personalization:lowcodemobile:1.+")
}
```

### Required SDK Levels

Your app's SDK levels must meet or exceed the following minimums.

| Setting      | Required         |
| :----------- | :--------------- |
| `minSdk`     | 26 (Android 8.0) |
| `compileSdk` | 36 (Android 16)  |
| Kotlin       | 2.4+             |

## Initialize the SDK

The host app owns SDK initialization. Initialize both the [Data 360 module](https://developer.salesforce.com/docs/data/data-cloud-engagement-mobile-sdk/guide/c360a-api-engagement-mobile-sdk-initialization.html) and Personalization modules in your `Application.onCreate()`. The SDK queues any content zone requests made before initialization completes, so you do not need to gate your UI on init status.

```kotlin
import com.salesforce.marketingcloud.cdp.CdpConfig
import com.salesforce.marketingcloud.sfmcsdk.SFMCSdk
import com.salesforce.marketingcloud.sfmcsdk.SFMCSdkModuleConfig
import com.salesforce.personalization.PersonalizationConfig

/* Initialization of the CDP module for data collection */
val flushRate = EventFlushRate.Quantity(quantity = 1)

val cdpConfig = CdpConfig.Builder(
    context = this,
    appId = "<Your Data 360 CDP App ID>", // Your CDP Mobile Connector app ID
    endpoint = "<Your Tenant Specific CDP Endpoint>" // Your CDP Mobile Connector endpoint
).eventFlushRate(flushRate)
 .build()

val personalizationConfig = PersonalizationConfig.Builder(this)
    .dataspace("default") // Optional — defaults to "default" if omitted
    .cdnUrl("<Your CDN URL>") // Your CDN URL from the Mobile Connector
    .build()

/* The CDP and Personalization configurations initialized above are provided to SFMCSdk.configure  */
SFMCSdk.configure(this, SFMCSdkModuleConfig.build {
    cdpModuleConfig = cdpConfig
    personalizationModuleConfig = personalizationConfig
})
{ initStatus ->
    Log.d(TAG, "SDK initialized: ${initStatus.status}")
}
```

**note:** In your production application, you must explicitly manage user consent using the solution provided in the Engagement Mobile SDK. See [Data 360 Consent Management](https://developer.salesforce.com/docs/data/data-cloud-engagement-mobile-sdk/guide/c360a-api-engagement-mobile-sdk-consent-management.html).

### Considerations

- Replace `"<Your CDP App ID>"`, `"<Your CDP Endpoint>"`, and `"<Your CDN URL>"` with the values provided by your Salesforce Marketing Cloud administrator.
- To avoid committing credentials, read these values from `AndroidManifest.xml` `<meta-data>` entries or a build configuration.
- To enable debug logging during development, add `SFMCSdk.setLogging(LogLevel.DEBUG, AndroidLogger())` before `SFMCSdk.configure(...)`, so logging is active for the whole init sequence. Remove this before building for production.

## Display a Content Zone

Once the SDK is initialized, use the `ContentZone` composable in Jetpack Compose. Pass the content zone identifier and a list of components the zone is allowed to render. The SDK fetches a decision from the backend, matches the component name returned, and renders the matching component.

After adding a ContentZone to your app code, create the matching content zone record in Salesforce Personalization. See [Set Up Mobile Content Zones](https://help.salesforce.com/s/articleView?id=mktg.persnl_experience_mobile_content_zones_register.htm) for instructions on defining personalization points, assigning components, and configuring engagement definitions.

### Jetpack Compose

```kotlin
import com.salesforce.personalization.lowcodemobile.ContentZone
import com.salesforce.personalization.ootbcomponents.SalesforceBanner
import com.salesforce.personalization.ootbcomponents.SalesforceRecommendations

@Composable
fun HomeScreen() {
    ContentZone(
        name = "HomeScreen",
        allowedComponents = listOf(
            SalesforceBanner(),
            SalesforceRecommendations()
        )
    )
}
```

`ContentZone` is a standard composable - place it anywhere in your layout alongside other content. The [Pull-to-refresh](#pull-to-refresh) example below shows it embedded within a scrollable screen.

The out-of-the-box component names registered internally are `"Salesforce_Banner"` and `"Salesforce_Recommendations"`.

### ContentZone Parameters

| Parameter                 | Required | Description                                                                                                  |
| :------------------------ | :------- | :----------------------------------------------------------------------------------------------------------- |
| `name`                    | Yes      | The content zone identifier, matching your backend configuration (case-sensitive).                           |
| `allowedComponents`       | Yes      | The `Components` the zone may render. If the backend returns a name not in this list, the fallback is shown. |
| `decisionsRequestContext` | No       | Optional context to bias personalization decisions.                                                          |
| `timeoutMs`               | No       | Fetch timeout in milliseconds. Default: 10,000 (10 seconds).                                                 |
| `controller`              | No       | `ContentZoneController` for programmatic refresh.                                                            |
| `loading`                 | No       | Composable shown while content is loading.                                                                   |
| `fallback`                | No       | Composable shown when content cannot be loaded or no component matches.                                      |

### Pull-to-refresh

Use a `ContentZoneController` to refresh the zone programmatically:

```kotlin
import androidx.compose.material3.pulltorefresh.PullToRefreshBox
import androidx.compose.runtime.remember
import com.salesforce.personalization.lowcodemobile.ContentZone
import com.salesforce.personalization.lowcodemobile.ContentZoneController
import com.salesforce.personalization.ootbcomponents.banner.SalesforceBanner
import com.salesforce.personalization.ootbcomponents.recs.SalesforceRecommendations
import kotlinx.coroutines.launch

@Composable
fun HomeScreen() {
    val zoneController = remember { ContentZoneController() }
    var isRefreshing by remember { mutableStateOf(false) }
    val scope = rememberCoroutineScope()

    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = {
            isRefreshing = true
            scope.launch {
                try {
                    zoneController.refresh()
                } finally {
                    isRefreshing = false
                }
            }
        }
    ) {
        Column(modifier = Modifier.verticalScroll(rememberScrollState())) {
            Text("Welcome back!") // Other content in your screen

            ContentZone(
                name = "HomeScreen",
                controller = zoneController,
                allowedComponents = listOf(
                    SalesforceBanner(),
                    SalesforceRecommendations()
                )
            )

            // Additional content below the zone
        }
    }
}
```

## Out-of-the-Box Components

The SDK ships with two pre-built components - `SalesforceBanner` and `SalesforceRecommendations` - that handle layout, styling, and configuration-driven engagement tracking out of the box. Use these when you want to display personalized content without writing a custom UI. Both support an `onTap` callback for custom tap handling; by default, tapping opens the `ctaUrl` if one is provided by the backend.

These components are available out-of-the-box in the UI and are registered under the names `"Salesforce_Banner"` and `"Salesforce_Recommendations"`.

### SalesforceBanner

```kotlin
ContentZone(
    name = "HomeScreen",
    allowedComponents = listOf(
        SalesforceBanner(
            onTap = { model ->
                // Custom tap handling - default behavior opens ctaUrl if provided
                Log.d("App", "Banner tapped: ${model.header}")
            }
        )
    ),
    loading = { CircularProgressIndicator() },
    fallback = { Text("Content unavailable") }
)
```

### SalesforceRecommendations

Pass a `DecisionsRequestContext` to bias recommendations based on what the user is currently viewing. All fields are optional - if you only supply `anchorId`, the system infers the type automatically.

```kotlin
val context = DecisionsRequestContext.Builder()
    .anchorId("PRODUCT_123")
    // Optional: explicitly specify the anchor type. If omitted, the system infers it from anchorId.
    .anchorDmoName("ssot__GoodsProduct__dlm")
    .contextualAttribute(name = "category", value = "shoes")
    .build()

ContentZone(
    name = "ProductRecommendations",
    allowedComponents = listOf(
        Recommendations(
            onTap = { event ->
                // Custom tap handling - default behavior opens ctaUrl if provided
                Log.d("App", "Tapped ${event.item.header} at index ${event.index}")
            }
        )
    ),
    decisionsRequestContext = context
)
```

### Custom Styling

Override the default appearance of out-of-the-box components by passing a style object:

```kotlin
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import com.salesforce.personalization.lowcodemobile.ContentZone
import com.salesforce.personalization.ootbcomponents.banner.BannerStyle
import com.salesforce.personalization.ootbcomponents.banner.SalesforceBanner

ContentZone(
    name = "MyScreen",
    allowedComponents = listOf(
        SalesforceBanner(
            style = BannerStyle(
                backgroundColor = Color(0xFFF5F5F5),
                headerTextColor = Color(0xFF1A1A1A),
                contentPadding = 16.dp
            )
        )
    )
)
```

## Custom Components

Implement the `Component<Model>` interface (package com.salesforce.personalization.lowcodemobile) to render a content zone with your own UI. Each component defines:

- `val name: String` - The component name that matches the backend experience template's component name.
- `val modelClass: KClass<Model>` - The Kotlin class reference for the component model.
- `validateAndCreateComponentModel(unvalidatedJson, componentContext)` - Validates the JSON payload and returns a Result.Success(model) or Result.Failure(exception).
- `@Composable Compose(model, componentContext)` - Renders the composable UI for the component.

### Define a custom component

Define a custom component with its own component name, model, and associated experience template in the backend. Give the component a unique name (for example, `CustomHero`), then create a matching experience template in the Core UI and a matching custom component in your app. Your model's fields and types must match the experience template's schema, though you don't need to use all of them.

```kotlin
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp
import coil.compose.AsyncImage
import com.salesforce.personalization.errors.PersonalizationException
import com.salesforce.personalization.lowcodemobile.Component
import com.salesforce.personalization.lowcodemobile.ComponentContext
import com.salesforce.personalization.lowcodemobile.ComponentModel
import com.salesforce.personalization.lowcodemobile.EngagementAction
import com.salesforce.personalization.lowcodemobile.TrackEngagementViewOnce
import com.salesforce.personalization.utils.Result
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json

@Serializable
data class HeroModel(
    val header: String,
    val imageUrl: String,
    val ctaText: String?
) : ComponentModel

class CustomHero : Component<HeroModel> {
    override val name = "CustomHero"
    override val modelClass = HeroModel::class

    internal companion object {
        private val json = Json { ignoreUnknownKeys = true }
    }

    override fun validateAndCreateComponentModel(
        unvalidatedJson: String,
        componentContext: ComponentContext
    ): Result<HeroModel, PersonalizationException.ContentZoneUnableToRender> {
        val model = json.decodeFromString<HeroModel>(unvalidatedJson)
        // Optionally, validate model (blank strings, no fallbacks, missing critical pieces) and if invalid:
        // return Result.Failure(PersonalizationException.ComponentDataModelInvalid(...))
        return Result.Success(model)
    }

    @Composable
    override fun Compose(model: HeroModel, componentContext: ComponentContext) {
        Column(
            modifier = Modifier
                .fillMaxWidth()
                .clickable {
                    // Track clicks when the user taps
                    componentContext.trackEngagement(EngagementAction.CLICK)
                    // You could add a tapUrl to the model and open/route as well
                }
        ) {
            // This example uses AsyncImage from the Coil dependency
            AsyncImage(
                model = model.imageUrl,
                contentDescription = model.header,
                modifier = Modifier.fillMaxWidth().height(200.dp),
                contentScale = ContentScale.Crop
            )
            Text(
                text = model.header,
                style = MaterialTheme.typography.titleMedium,
                modifier = Modifier.fillMaxWidth(),
                textAlign = TextAlign.Center
            )
            model.ctaText?.let {
                Text(
                    text = it,
                    modifier = Modifier.fillMaxWidth(),
                    color = MaterialTheme.colorScheme.primary,
                    textAlign = TextAlign.Center
                )
            }
        }
        // Track a view once per personalization
        TrackEngagementViewOnce(componentContext)
    }
}

// Usage
ContentZone(
    name = "HomeScreen",
    allowedComponents = listOf(CustomHero())
)
```

### Define a multi-item custom component

For a component that renders a list (like `SalesforceRecommendations`), use the per-item variants of the engagement functions to report engagement for each item in the list.

```kotlin
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.size
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import coil.compose.AsyncImage
import com.salesforce.personalization.errors.PersonalizationException
import com.salesforce.personalization.lowcodemobile.Component
import com.salesforce.personalization.lowcodemobile.ComponentContext
import com.salesforce.personalization.lowcodemobile.ComponentModel
import com.salesforce.personalization.lowcodemobile.EngagementAction
import com.salesforce.personalization.lowcodemobile.TrackEngagementViewOncePerItem
import com.salesforce.personalization.utils.Result
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json

@Serializable
data class ItemListModel(
    val sectionHeader: String?,
    val items: List<ItemModel>
) : ComponentModel

@Serializable
data class ItemModel(
    val id: String,
    val title: String,
    val imageUrl: String,
    val description: String
)

class CustomItemList : Component<ItemListModel> {
    override val name = "CustomItemList"
    override val modelClass = ItemListModel::class

    internal companion object {
        private val json = Json { ignoreUnknownKeys = true }
    }

    override fun validateAndCreateComponentModel(
        unvalidatedJson: String,
        componentContext: ComponentContext
    ): Result<ItemListModel, PersonalizationException.ContentZoneUnableToRender> {
        val model = json.decodeFromString<ItemListModel>(unvalidatedJson)
        // Optionally, validate model (blank strings, no fallbacks, missing critical pieces) and if invalid:
        // return Result.Failure(PersonalizationException.ComponentDataModelInvalid(...))
        return Result.Success(model)
    }

    @Composable
    override fun Compose(model: ItemListModel, componentContext: ComponentContext) {
        Column(
            modifier = Modifier.fillMaxWidth(),
            verticalArrangement = Arrangement.spacedBy(16.dp)
        ) {
            model.sectionHeader?.takeIf { it.isNotBlank() }?.let { header ->
                Text(
                    text = header,
                    style = MaterialTheme.typography.titleMedium,
                    modifier = Modifier.fillMaxWidth(),
                    textAlign = TextAlign.Center
                )
            }
            model.items.forEachIndexed { index, item ->
                ComposeItem(item, componentContext, index)
            }
        }
    }
}

@Composable
private fun ComposeItem(model: ItemModel, componentContext: ComponentContext, index: Int) {
    Row(
        verticalAlignment = Alignment.CenterVertically,
        modifier = Modifier.clickable {
            // Track clicks when the user taps
            componentContext.trackEngagementPerItem(index, EngagementAction.CLICK)
            // You could add a tapUrl to the model and open/route as well
        }
    ) {
        // Image on the left. This example uses AsyncImage from the Coil dependency.
        AsyncImage(
            model = model.imageUrl,
            contentDescription = model.title,
            modifier = Modifier.size(100.dp),
            contentScale = ContentScale.Crop
        )
        // Text on the right
        Column(
            modifier = Modifier.weight(1f),
            verticalArrangement = Arrangement.Center
        ) {
            Text(
                text = model.title,
                fontWeight = FontWeight.SemiBold,
                maxLines = 1,
                overflow = TextOverflow.Ellipsis
            )
            Spacer(modifier = Modifier.height(8.dp))
            Text(
                text = model.description,
                fontWeight = FontWeight.Normal,
                maxLines = 1,
                overflow = TextOverflow.Ellipsis
            )
        }
    }
    // Track a view once per personalization, per item
    TrackEngagementViewOncePerItem(componentContext, index)
}

// Usage
ContentZone(
    name = "HomeScreen",
    allowedComponents = listOf(CustomItemList())
)
```

## See Also

- [Create a Mobile Experience Template](https://help.salesforce.com/s/articleView?id=mktg.persnl_experience_mobile_template_create.htm)

## Engagement Tracking

Before engagement events are recorded, ensure your engagement definitions (View, Click) are configured in the Data 360 mobile connector. See [Set Up Mobile Engagement Tracking](https://help.salesforce.com/s/articleView?id=mktg.persnl_experience_mobile_engagement_tracking.htm) for instructions on defining engagement actions alongside your components and content zones.

Out-of-the-box components (`SalesforceBanner`, `SalesforceRecommendations`) track `View` and `Click` engagement automatically. These are the only two actions currently supported end-to-end. The SDK accepts custom action strings for future expansion.

For custom components, engagement is not automatic - you must call these methods explicitly from your component code:

| Function                                                  | Use for                                                                                               |
| :-------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
| `componentContext.trackEngagement(action)`                | Clicks on a single-item component (for example, `CustomHero`)                                         |
| `componentContext.trackEngagementPerItem(index, action)`  | Clicks on an item within a multi-item component (for example, `CustomItemList`)                       |
| `TrackEngagementViewOnce(componentContext)`               | Views of a single-item component - a Composable, call once per personalization                        |
| `TrackEngagementViewOncePerItem(componentContext, index)` | Views of an item within a multi-item component - a Composable, call once per item per personalization |

See [Define a custom component](#define-a-custom-component) and [Define a multi-item custom component](#define-a-multi-item-custom-component) above for both in use.

## Preview

The SDK supports previewing personalized content via QR code or preview URL. When a URL containing the `sfp-preview` parameter is opened, the SDK renders preview content in all active content zones.

Before using preview, make sure:

1. Your app is configured to handle URL schemes or app links (via `AndroidManifest.xml` intent filters).
2. The base URL is set in your Data 360 mobile connector configuration.

```kotlin
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        PersonalizationSdk.handlePreviewIntent(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        PersonalizationSdk.handlePreviewIntent(intent)
    }
}
```

## Design-Time Rendering

Use `MockDataContentZone` to render components with mock data for styling and layout without any backend setup or networking. This is not related to QR-code based previewing - it simply lets you see how components look during development.

```kotlin
@Preview // Compose design-time rendering - not related to QR-code based previewing
@Composable
fun HomeScreenPreview() {
    MockDataContentZone(
        name = "HomeScreen",
        allowedComponents = listOf(SalesforceBanner(), SalesforceRecommendations()),
        mockContent = Result.Success(myMockComponentModel) // replace myMockComponentModel with the model you need, for example:
        // BannerModel(
        // 	header = "Hello",
        //	imageUrl = "https://example.com/banner.png",
        //	ctaText = "Find out more"
        // )
    )
}
```

To try out your `fallback` composable, pass a `Result.Failure`:

```kotlin
@Preview
@Composable
fun ErrorStatePreview() {
    MockDataContentZone(
        name = "HomeScreen",
        allowedComponents = listOf(SalesforceBanner()),
        mockContent = Result.Failure(
            PersonalizationException(PersonalizationException.ContentZoneUnableToRender("Preview Error"))
        )
    )
}
```

## Error Handling

The SDK uses `PersonalizationException` with a `Type` enum for error reporting:

| Type               | Description                                               |
| :----------------- | :-------------------------------------------------------- |
| `UNKNOWN`          | An unknown error occurred.                                |
| `INITIALIZATION`   | The SDK has not been initialized or failed to initialize. |
| `CONSENT`          | User consent is not set to opt-in.                        |
| `REQUEST_INVALID`  | The request parameters are invalid.                       |
| `NETWORK`          | A network error occurred during the fetch.                |
| `RESPONSE_INVALID` | The server response could not be parsed.                  |
| `TIMEOUT`          | The fetch request exceeded the timeout duration.          |

ContentZone handles errors internally. If no `fallback` is provided, the zone logs the error and shows nothing - this is the typical production behavior. If you want to display fallback content, pass a `fallback` composable. The following example is for illustration only - consider what behavior is appropriate for your production app:

```kotlin
ContentZone(
    name = "HomeScreen",
    allowedComponents = listOf(SalesforceBanner()),
    fallback = { error ->
        when ((error as? PersonalizationException)?.type) {
            PersonalizationException.Type.TIMEOUT ->
                Text("Request timed out. Pull to refresh.")
            PersonalizationException.Type.NETWORK ->
                Text("No network connection.")
            else ->
                Text("Content unavailable.")
        }
    }
)
```

<!-- document id=1b4b282f4c47372a8cb3da63d333c90b4a7a401806c3984a4d959da746e4b16b url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/batch-personalization-output-dmo.md -->

# Batch Personalization Output DMO

The Batch Personalization Output Data Model Object (DMO) captures information about the decisions created for a batch personalization.

## Object API Name

The API name is automatically generated from the batch personalization name.

## Primary Key

Personalization Batch Decision Output Id (`Id__c`).

## All Fields

| Field Name                                             | Field API Name                      | Description                                                                                                                                                                                                                                                                                 | Data Type |
| :----------------------------------------------------- | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------- |
| Profile Id                                             | `ProfileID__c`                      | The unified individual ID of the record that's personalized (if available) or the individual ID.                                                                                                                                                                                            | Text      |
| Individual Id                                          | `IndividualId__c`                   | The individual identifier used during personalization.                                                                                                                                                                                                                                      | Text      |
| Key Qualifier Personalization Batch Decision Output Id | `KQ_Id__c`                          | The internal ID used by Data Cloud for table indexing.                                                                                                                                                                                                                                      | Text      |
| Segment Id                                             | `SegmentId__c`                      | The ID of the segment the batch Personalization is run on.                                                                                                                                                                                                                                  | Text      |
| Personalization Point Id                               | `PersonalizationPointId__c`         | The ID of the personalization point that is used to generate the activation data.                                                                                                                                                                                                           | Text      |
| Personalization Point Api Name                         | `PersonalizationPointApiName__c`    | The API name or developer name of the personalization point that is used to generate the activation data.                                                                                                                                                                                   | Text      |
| Personalization Decision Id                            | `PersonalizationDecisionId__c`      | The ID of the personalization decision selected in the personalization point that is used to generate the activation data.                                                                                                                                                                  | Text      |
| Personalization Batch Decision Id                      | `PersonalizationBatchDecisionId__c` | The ID of the batch personalization that created the output.                                                                                                                                                                                                                                | Text      |
| Personalization Id                                     | `PersonalizationId__c`              | The unique identifier for the personalization request that is generated by Personalization.                                                                                                                                                                                                 | Text      |
| Last Updated Date Time                                 | `LastUpdatedDateTime__c`            | The date and time when the personalization is performed.                                                                                                                                                                                                                                    | DateTime  |
| Activation Data                                        | `ActivationData__c`                 | The JSON payload containing the personalization response returned by the personalization platform for the given individual, unified individual, personalization point, and personalization decision. The JSON payload structure is similar to a standard personalization decision response. | Text      |
| Unified Individual Id                                  | `UnifiedIndividualId__c`            | The unified individual ID of the record that’s personalized.                                                                                                                                                                                                                                | Text      |

<!-- document id=2be720c3a8fbcf71d14d85639727d8e50b385dad744cbda592493f99eec42cb7 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/web-integration/configure-web-personalization/configure-content-security-policies.md -->

# Configure Content Security Policies for Personalization

Content Security Policies (CSP) help secure web applications by limiting loadable and executable JavaScript resources. While implementing Personalization on your website using Interactions SDK and Web Personalization Manager (WPM), you must configure certain CSPs to ensure secure and seamless functionality.

At this time, Interactions SDK and WPM use inline scripts, necessitating their enablement within your CSP. Due to potential security implications, we strongly recommend implementing a CSP nonce. A nonce is a cryptographically-generated random value that changes with each page load. By including the correct nonce in your CSP and `<script>` tags, you explicitly allowlist these specific scripts, preventing the execution of any other inline scripts.

If you can't implement a nonce-based CSP, you can alternatively use the `unsafe-inline` source expression. However, using `unsafe-inline` is less secure than nonce-based CSPs and should only be used when absolutely necessary.

## Implement a CSP Nonce

To implement a nonce-based CSP, generate a unique, random nonce on your server for every HTTP response and include it in your CSP header. For detailed information about the `nonce` CSP attribute, see [nonce](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce).

```
Content-Security-Policy:
  script-src 'self' 'nonce-<unique-nonce-value>' <webSdkUrl>;
  style-src 'self' 'nonce-<unique-nonce-value>' # Same nonce as script-src
```

**important:** Use the same nonce value for both the `script-src` and `style-src` directives in your CSP.

Then, include the generated nonce in the `<script>` and `<style>` tags for the web SDK.

```html
<script nonce="<unique-nonce-value>" src="{webSdkUrl}"></script>
```

**note:** Replace `<unique-nonce-value>` with the actual nonce you generated on your server.

If opting for this approach to configure CSPs, make sure that you use a server-side framework that supports nonce generation and injection. Also make sure that you apply the same nonce value to the CSP header and `<script>` and `<style>` tags on your web page.

## Set the unsafe-inline Source Expression

The simplest way to enable and use the web SDK and WPM is adding the `unsafe-inline` source expression to your CSP.

```
Content-Security-Policy:
  script-src 'self' 'unsafe-inline' <webSdkURL>;
  style-src 'self' 'unsafe-inline';
```

While using `unsafe-inline` is less secure, it allows unrestricted execution of inline scripts and dynamically evaluated code. Using `unsafe-inline` is especially helpful for development or quick implementation testing.

## Content Security Policies for WPM

While Interactions SDK can function with a nonce-based CSP, WPM requires the `unsafe-inline` source expression within the `style-src` directive due to [Lightning Web Components (LWC)](https://developer.salesforce.com/docs/component-library/overview/components) using inline styles. WPM can operate correctly without the `unsafe-inline` source expression when your CDN URLs are allowlisted.

```
Content-Security-Policy:
  script-src 'self' <webSdkUrl> <WPMScriptUrl>;
  style-src 'self' 'unsafe-inline';
```

**note:** Replace `<webSdkUrl>` with the SDK URL and `<WPMScriptUrl>` with the URL that hosts your WPM script. For information on URL specifications in CSP, see [`<host-source>`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#host-source) on MDN Web Docs.

## Additional Notes

- If you’re using other Salesforce SDKs or third-party libraries, make sure that their script sources are also accounted for in your CSP.
- Regularly audit and update your CSP configurations to adapt to changes in your implementation and its dependencies.

<!-- document id=909fbc2dcadcc7f41f763021facb9bd8fe2637911acdfd110e2f5af7a8366596 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/web-integration/configure-web-personalization/configure-flicker-defense.md -->

# Configure Flicker Defense

Page flicker is a visible glitch that occurs when a web page loads or updates content, causing it to flash or change content rapidly. This issue is common in personalization or A/B testing scenarios, where a web page’s original content is displayed momentarily before being replaced with personalized or variant versions of content.

The `FlickerDefenseConfig` interface helps prevent page flicker caused by rendering personalized content returned by Personalization on web pages.

## FlickerDefenseConfig Interface

The `FlickerDefenseConfig` interface defines the configuration settings for Flicker Defender.

```javascript
export interface FlickerDefenseConfig {
    redisplayTimeoutMilliseconds: number
    renderPersonalizationAfterTimeoutElapsed: boolean
}

export const DEFAULT_FLICKER_DEFENSE_CONFIG = {
    redisplayTimeoutMilliseconds: 2000,
    renderPersonalizationAfterTimeoutElapsed: false
}
satisfies FlickerDefenseConfig
```

The `FlickerDefenseConfig` interface includes the properties in this table.

| Property                                   | Description                                                                                                    | Type    | Default Value |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ------- | ------------- |
| `redisplayTimeoutMilliseconds`             | The time (in milliseconds) to wait before redisplaying hidden elements on the page                             | Number  | `2000`        |
| `renderPersonalizationAfterTimeoutElapsed` | Determines whether to proceed with or block the rendering of personalized content after the timeout has lapsed | Boolean | `false`       |

## Custom Configuration

You can customize Flicker Defense by specifying your own values for `redisplayTimeoutMilliseconds` and `renderPersonalizationAfterTimeoutElapsed`, as shown in this example.

```javascript
export interface FlickerDefenseConfig {
    redisplayTimeoutMilliseconds: 3000
    renderPersonalizationAfterTimeoutElapsed: true
}
```

**note:** The default values provided in the Flicker Defense configuration is sufficient for most use cases. Modify these values only if necessary.

<!-- document id=afc94b77228dde4155844d4ffd2405d6572194ffee72de0c4730ec3a0592f8c0 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/web-integration/configure-web-personalization.md -->

# Configure the Personalization Module

Salesforce Interactions SDK includes the Personalization module that enables you to define and customize how personalized data received from Personalization is rendered on your website. This module includes objects using which you can publish personalized experience configurations that business users generate using [Web Personalization Manager](https://help.salesforce.com/s/articleView?id=sf.persnl_web_personalization_manager.htm). Additionally, you can also configure webpage flicker defense and specify additional destinations to which you can route engagement data.

Review these articles to know more about how to initialize and configure the Personalization module.

- [Initialize the Personalization Module](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/configure-web-personalization/initialize-einstein-personalization-module.md)
- [Configure Flicker Defense](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/configure-web-personalization/configure-flicker-defense.md)

<!-- document id=10d616f95b66284665d407b53d9554c5c7b63effac6261243886da12162f7611 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/decisioning-api/decisioning-api-reference.md -->

# Decisioning API

Request personalized content for data derived from Salesforce Data Cloud.

## Base URI

`https://{tenantSpecificEndpoint}`

Replace `tenantSpecificEndpoint` in the base URI with your Data Cloud tenant’s Tenant Specific Endpoint before adding this code to your Sitemap. To know how to retrieve your Tenant Specific Endpoint, see [Share Ingestion API Developer Information](https://help.salesforce.com/s/articleView?id=sf.c360_a_developer_required_information.htm).

## Supported Operations

| Supported Operation     | HTTP Method | URI                          |
| ----------------------- | ----------- | ---------------------------- |
| Request personalization | `POST`      | `/personalization/decisions` |

<!-- document id=f07f15c9ad15b1bd4dd4e9d7d518f279a7537e9982aed0498b89fe97951b2a10 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/decisioning-api/decisioning-api-pipeline-diagnostics.md -->

# Decisioning API Pipeline Diagnostics

Personalization assigns diagnostic codes to the execution of all requests made to the Decisioning API. Diagnostic codes are returned in the response for an authenticated request and included in the associated PersonalizationLog entry for unauthenticated requests.

**important:** While diagnostic codes resemble HTTP error codes, avoid interpreting them as such. They're specific to the Decisioning API and serve a different purpose.

## Informational Diagnostic Codes

Information diagnostic codes provide information about the normal operation of the Decisioning API, indicating that either no issues or only minor issues were encountered.

### 200: OK

No unexpected or exceptional issues occurred during the execution of the request.

### 201: NO_DECISION_QUALIFIED

**Diagnostic message:** No Decision qualified

This diagnostic code appears in requests where the individual doesn’t qualify for any of the associated personalization point’s configured decisions.

## Processing and General 4XX Diagnostic Codes

Processing and general `4XX` diagnostic codes indicate issues that occurred due to client-side errors or issues with the request itself. Such errors typically require you to correct the request so that they can be processed successfully.

### 401: POINT_NOT_CONFIGURED

**Diagnostic message:** Requested Personalization Point is not configured.

This diagnostic code indicates that Personalization was unable to locate the personalization point specified in the request, due to one or more of the following reasons.

- There’s a typo in the `name` or `id` of the personalization point specified in the request. To avoid this error, ensure that the personalization point details matches those that you configured.
- Incorrect Tenant Specific Endpoint.
- Temporary network connectivity issues while fetching a personalization point configuration. If network connectivity impacts your request, retry your request after 30 seconds.
- The personalization point configuration couldn’t be synchronized with backend services. Edit and re-save the personalization point and retry your request.
- Conflicting IDs and names of more than one personalization point.

### 402: UNIDENTIFIED_POINT_REQUESTED

**Diagnostic message:** Requested Personalization Point is missing id and name

This diagnostic code indicates that your request is missing properties needed to identify your requested personalization point. To accurately identify a personalization point, your API request must include at least one appropriate identifier such as `name` or `id`.

```json
"personalizationPoints": [
    {
        "name": "DevNameOfPersonalizationPoint"
    }
]
```

### 403: NO_POINTS_REQUEST

**Diagnostic message**: Request contained no Personalization Points

This diagnostic code indicates that the request didn’t contain any personalization points that could be used to process the request. This issue can occur if all personalization points specified in the request are rejected due to issues described by `401` and `402` diagnostic codes.

### 405: PERMISSION_DENIED

**Diagnostic message**: Permission Denied

This diagnostic code indicates that your request couldn’t be processed due to permission-related issues such as:

- Attempting to request a CoPilot Action personalization decision in an unauthenticated requested. To resolve this issue, either ensure the request is authenticated, or request a non-CoPilot personalization.
- Attempting to request batch personalization decisions for CoPilot Actions. CoPilot Action personalizations must be requested individually.
- Attempting to request a personalization decision without having Personalization enabled in your instance.

### 406: TOO_MANY_REQUESTS

**Diagnostic message:** Too Many Requests

This internal-only diagnostic code lets internal users know that our backend services are handling too many requests. If backend services encounter this issue, your API requests will receive a `429` HTTP response code, indicating that you must throttle or hold-off requests.

### 407: DECISION_NOT_FOUND

**Diagnostic message:** No Decision found with specified Decision Id

This diagnostic code is logged when a request includes a `decisionId` field, but the specified decision can’t be found for the requested personalization point. To resolve this issue, check your personalization point’s configuration in the UI and ensure that the decision you’re requesting by ID is mapped to that personalization point.

### 408: SPECIFIED_DECISION_NOT_SUPPORTED

**Diagnostic message:** Specified Decision Feature is not supported for unauthenticated calls

This internal-only diagnostic code indicates that an unauthenticated request included a `decisionId` field. Such requests result in a `400` HTTP response with the message “Specified Decision Feature is not supported for unauthenticated calls”.

## Qualifying Stage 4XX Error Codes

### 421: PERSONALIZER_NOT_SELECTED

**Diagnostic message:** No Personalizer was selected

This diagnostic code is logged when Personalization attempts to identify which personalizer to invoke for the request but was unable to find one. This error can occur when:

- No decision qualifies for the personalization request, as described by codes `407` and `408`. To avoid this issue, ensure that a valid decision qualifies for the request and that a valid personalizer is selected for the request.
- No valid personalizer is configured for the decision selected for the request. To resolve this issue, check your personalization point configuration in the UI and ensure a personalizer is configured for the decision being invoked in the request.

## Personalizing Stage 4xx Error Codes

### 431: PERSONALIZER_TYPE_NOT_FOUND

**Diagnostic message:** Requested Personalizer Type is not found

This diagnostic code indicates that a problem with the personalization point’s configuration is preventing Personalization from recognizing the personalizer type associated with an associated decision.

## Processing Stage and General 5xx Error Codes

### 500: UNEXPECTED_ERROR

**Diagnostic message:** Unexpected Error

This diagnostic code is logged when there is an error while formatting content received from the personalizer for writing to the `PersonalizationLog`, resulting in the `Content` property of the log being empty. Additionally, errors can occur while preparing to record the request results to the `PersonalizationLog`.

### 501: INTERRUPTION

**Diagnostic message:** Server interrupted

This diagnostic code indicates that your request couldn’t be processed due to a low-level interruption. Retry your request.

### 502: TIMEOUT

**Diagnostic message:** Timeout

This internal-only diagnostic code indicates that your request failed due to a timeout.

Although this code doesn’t get logged as a diagnostic code, it’s used in the message of an error response. If you encounter this error during a REST API request, it’ll result in a `503 SERVICE UNAVAILABLE` response with the message “Timeout Exceeded".

### 503: MODEL_LOOKUP_FAILURE

**Diagnostic message:** Failed to lookup Points from Process Object Service

This internal-only diagnostic code indicates that Personalization couldn’t retrieve the configuration information for the personalization points specified in your request.

Although this code doesn’t get logged as a diagnostic code, it’s used in the message of an error response. If you encounter this error during a REST API request, it’ll result in a `503` response with the message “Failed to lookup tenant metadata".

## Augmenting Stage 5xx Error Codes

### 511: QUERY_SERVICE_ERROR

**Diagnostic message:** Failed to call Query Service to look up profile

This diagnostic code indicates that an error occurred while calling Data Cloud Query Service to fetch an individual’s profile Data Graph.

Depending on your configuration, your request request either proceeds, treating the individual as anonymous, or returns a `503` failure response with the message “Empty response from Query Service when querying for profile”.

### 512: QUERY_SERVICE_MISSING_PROFILE

**Diagnostic message:** Query Service response missing profile

This diagnostic code indicates that Personalization successfully called the Data Cloud Query Service to fetch an individual’s profile data graph, but the response showed that the individual has no profile data graph.

In such cases, your request gets processed, treating the individual as anonymous.

### 513: CANNOT_PARSE_PROFILE

**Diagnostic message:** Failed to parse profile

This diagnostic code indicates that the response to Personalization’s call to the Data Cloud Query Service to fetch an individual’s profile data graph contains data in an unexpected format. As a result of this error:

- targeting rules that require a profile data graph fail to execute properly
- recommenders can’t use the individual’s profile data graph to personalize recommendations

## Qualifying Stage 5xx Error Codes

### 521: RULE_EVALUATION_FAILURE

**Diagnostic message:** Failed to execute rules for Decision

This diagnostic code indicates that the evaluation of targeting rules for the associated decision encountered an error. This error occurs if:

- **Targeting rules were misconfigured**. To resolve this issue, check the configuration of your targeting rules for the decision in the UI.
- **Rules couldn’t be evaluated at runtime due to unexpected data format in the associated profile data graph**. To fix this issue, check the individual’s profile data graph to see if there are any data type mismatches.

### 522: EXPERIMENT_EVALUATION_FAILURE

**Diagnostic message:** Failed to execute experiment

This diagnostic code indicates that an error occurred while evaluating an experiment, resulting in no personalizer being selected for use in the request.

To resolve this issue, check the configuration of the experiment associated with the specified personalization point.

### 523: VALIDATION_ERROR_RULES_CONFIGURATION

**Diagnostic message:** Validation error of rules configurations

This diagnostic code indicates that an error occurred while evaluating the targeting rules for a given decision for the individual’s profile data graph. This error occurs due to reason similar to those that result in diagnostic code `521: RULE_EVALUATION_FAILURE`.

## Personalizing Stage 5xx Error Codes

### 531: CONTENT_RETRIEVAL_ERROR_FROM_RECOMMENDATION_SERVICE

**Diagnostic message:** Error retrieving content from Recommendation Service

This diagnostic code indicates that an error occurred while calling the Recommendation Service to retrieve personalized content for this request. This error could involve either a standard recommendation personalizer or a CoPilot Action personalizer. Additional details about the error are included in the accompanying error message.

### 532: PERSONALIZER_RUNTIME_EXCEPTION

**Diagnostic message:** Error retrieving content

This diagnostic code indicates that the Recommendation Service encountered an error while retrieving personalized content for this request. Additional details about the error are included in the accompanying error message.

### 533: RECOMMENDER_CONTENT_SIZE_EXCEEDED

**Diagnostic message:** Content items returned from Recommender exceed limit

This diagnostic code indicates that Personalization has received more items than expected when calling the Recommendation Service to retrieve personalized content for this request. The response is truncated to include only the maximum number of items allowed.

<!-- document id=468091b94c480f3f64874a3b93abc6ddf6d8184bcb93271458e02a7d0a9a9337 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/web-integration/example-sitemap.md -->

# Example Sitemap

Here's an example of a Salesforce Interactions SDK sitemap that tracks user engagement when a visitor lands on the homepage and identifies content zones where personalized content can be injected.

**important:** This example Sitemap is for reference only. Avoid using this Sitemap code or the provided frontend logic in your own implementation as it may not produce the same results.

```javascript
/* ========= START: PERSONALIZATION INITIALIZATION ========= */
SalesforceInteractions.Personalization.Config.initialize({
  customFlickerDefenseConfig: {
    redisplayTimeoutMilliseconds: 2000,
    renderPersonalizationAfterTimeoutElapsed: false,
  },
});
/* ========= END: PERSONALIZATION INITIALIZATION ========= */
SalesforceInteractions.init({
  personalization: {
    dataspace: "default",
  },
  consents: [
    {
      purpose: SalesforceInteractions.ConsentPurpose.Tracking,
      provider: "Example Consent Manager",
      status: SalesforceInteractions.ConsentStatus.OptIn,
    },
  ],
}).then(() => {
  const sitemapConfig = {
    pageTypeDefault: {
      name: "default",
      interaction: {
        name: "default",
        eventType: "userEngagement",
      },
    },
    pageTypes: [
      {
        name: "home",

        isMatch: () => window.location.pathname === "/",

        interaction: {
          name: "home view",
          eventType: "userEngagement",
        },
        contentZones: [
          { name: "recommendations_1", selector: "section.product_recs" },
          { name: "recommendations_2", selector: "div#customer-stories" },
        ],
      },
    ],
  };
  SalesforceInteractions.initSitemap(sitemapConfig);
  /* === SPA Websites === */
  let currentUrl = window.location.href;
  setInterval((_) => {
    if (currentUrl !== window.location.href) {
      currentUrl = window.location.href;
      SalesforceInteractions.reinit();
    }
  }, 500);
});
```

<!-- document id=dd225ef192d3467e152f755feddcece4f10e0ff1cee571f785f63a01b33f1e7e url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/experiment-cohort-dmo.md -->

# Experiment Cohort DMO

The Experiment Cohort DMO defines the metadata of the cohorts in an experiment.

## Object API Name

`ssot__AbnExperimentCohort__dlm`

## Primary Key

Abn Experiment Cohort Id (`Id__c`)

## All Fields

| Field Name         | Field API Name        | Description                                                                                                  | Data Type |
| :----------------- | :-------------------- | :----------------------------------------------------------------------------------------------------------- | :-------- |
| AbnExperiment      | `AbnExperimentId__c`  | Identifier for the parent experiment.                                                                        | text      |
| Name               | `Name__c`             | The name of the experiment.                                                                                  | text      |
| Description        | `Description__c`      | Optional description for the experiment.                                                                     | text      |
| Developer Name     | `DeveloperName__c`    | The developer of the experiment.                                                                             | text      |
| IsControl          | `IsControl__c`        | Indicates if the cohort is a control cohort. An experiment can have only one controlling cohort.             | boolean   |
| Allocation Weight  | `AllocationWeight__c` | The weight of the cohort in an experiment. The total weight for all cohorts in an experiment must equal 100. | number    |
| Personalizer       | `PersonalizerId__c`   | Identifier for the personalization recommender.                                                              | text      |
| Last Modified Date | `LastModifiedDate__c` | The date when the experiment was last modified.                                                              | date      |
| Created Date       | `CreatedDate__c`      | The date when the experiment was created.                                                                    | date      |

<!-- document id=3b27193a77c39b7a63fe99cae11c4267737ecf2fb19a8b90294825f707ea6c74 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/experiment-dmo.md -->

# Experiment DMO

The Experiment DMO defines the metadata of the experiments.

## Object API Name

`ssot__AbnExperiment__dlm`

## Primary Key

Abn Experiment Id (`Id__c`)

## All Fields

| Field Name                  | Field API Name                 | Description                                                                                                                                        | Data Type |
| :-------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- |
| Name                        | `Name__c`                      | The name of the experiment.                                                                                                                        | text      |
| Description                 | `Description__c`               | Optional description for the experiment.                                                                                                           | text      |
| Developer Name              | `DeveloperName__c`             | The developer of the experiment.                                                                                                                   | text      |
| Started Date Time           | `StartedDateTime__c`           | The date and time the experiment started, if applicable.                                                                                           | dateTime  |
| Stopped Date Time           | `StoppedDateTime__c`           | The date and time the experiment stopped, if applicable.                                                                                           | dateTime  |
| Experiment State            | `ExperimentState__c`           | The user-configurable state of the experiment.                                                                                                     | text      |
| Personalization Schema      | `PersonalizationSchemaId__c`   | The schema of the experiment if the experiment uses a custom schema.                                                                               | text      |
| Personalization Schema Type | `PersonalizationSchemaType__c` | The schema of the experiment if the experiment uses a standard schema.                                                                             | text      |
| External Source Id          | `ExternalSourceId__c`          | The link to the external data source system from where the record originated, if applicable.                                                       | text      |
| Profile Data Graph          | `ProfileDataGraphId__c`        | The profile data graph. This value is required only if the experiment has recommendation cohorts.                                                  | text      |
| Primary Metric              | `PrimaryMetric__c`             | The primary metric to evaluate the success of the experiment.                                                                                      | text      |
| Experiment Source           | `ExperimentSource__c`          | The builder or application in which the experiment is created. For example, Personalization App, CMS Content, Experience Builder, or Flow Builder. | text      |

<!-- document id=ab8c1df6785a6bf1d46297cfd895ebe2e5ab670380f859048babe28ca0a2313f url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/experimentation-assignment-api/experimentation-api-reference.md -->

# Experimentation Assignment API

Use the Experimentation Assignment API to request experiment cohort assignments for your users based on data from Salesforce Data 360.

## Base URI

`https://{tenantSpecificEndpoint}`

Replace `tenantSpecificEndpoint` in the base URI with the Tenant Specific Endpoint of your Data 360 tenant before adding this code to your Sitemap. To find your Tenant Specific Endpoint, see [_Data 360 Integration Guide_: Share Ingestion API Developer Information](https://developer.salesforce.com/docs/data/data-cloud-int/guide/c360-a-developer-required-information.html).

## Supported Operations

| Supported Operation           | HTTP Method | URI                                            |
| ----------------------------- | ----------- | ---------------------------------------------- |
| Request experiment assignment | `POST`      | `/experimentation/v1/authenticated/assignment` |

<!-- document id=87e6a0d7c0f14d57795d1a7e21dedf857661e0ce20313852f19d5c1de0498065 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/experimentation-assignment-api/experimentation-api-pipeline-diagnostics.md -->

# Experimentation Assignment API Pipeline Diagnostics

Experimentation assigns diagnostic codes to every request you make to the Experimentation Assignment API. The API returns these codes in the response for authenticated requests and includes them in the associated ExperimentationLog entry.

**important:** While diagnostic codes resemble HTTP status codes, they're specific to the Experimentation Assignment API. Don't interpret them as standard HTTP errors.

## Informational Diagnostic Codes

Informational codes indicate normal operation or minor processing notes that don't prevent the request from completing.

### 200: OK

The request executed successfully without unexpected issues.

### 204: NO_EXPERIMENT_QUALIFIED

**Diagnostic message:** No Experiment qualified

The individual doesn’t qualify for any of the associated experiments in the request.

## Processing and General 4XX Diagnostic Codes

Processing and general `4XX` diagnostic codes indicate issues that occurred due to client-side errors or issues with the request itself. Such errors typically require you to correct the request so that they can be processed successfully.

### 401: EXPERIMENT_NOT_CONFIGURED

**Diagnostic message:** Requested Experiment is not configured.

The Experimentation service cannot locate the experiment specified in the request. This issue occurs when:

- The experiment `name` or `ID` in the request contains a typo. Ensure the experiment details match the configuration in Data 360.
- The request uses an incorrect Tenant Specific Endpoint.
- A temporary network issue impacted the request. Retry the request after 30 seconds.
- Backend services failed to synchronize the experiment configuration. To resolve, edit and save the experiment, and then retry the request.
- The request contains conflicting IDs and names for multiple experiments.

### 406: TOO_MANY_REQUESTS

**Diagnostic message:** Too Many Requests

Internal backend services are handling a high volume of requests. If this occurs, the API returns an HTTP 429 response code. Throttle or hold-off your requests to resolve this issue.

### 420: NO_EXPERIMENTS_REQUEST

**Diagnostic message**: Request contained no experiments.

The request doesn't contain any valid experiments for processing. This error can occur if the service rejects all experiments in the request due to issues identified by codes `401` or `402`.

## Processing Stage and General 5xx Error Codes

### 500: UNEXPECTED_ERROR

**Diagnostic message:** Unexpected Error

The service encountered an error while formatting content for the `ExperimentationLog` or while recording request results.

### 501: INTERRUPTION

**Diagnostic message:** Server interrupted

A low-level server interruption prevented processing. Retry the request.

### 502: TIMEOUT

**Diagnostic message:** Timeout

This internal-only diagnostic code indicates that your request failed due to a timeout.

This internal code indicates a request timeout. While the service doesn't include this code in the response body, it triggers a `503 SERVICE UNAVAILABLE` response with the message "Timeout Exceeded".

### 503: MODEL_LOOKUP_FAILURE

**Diagnostic message:** Failed to lookup Experiments from Process Object Service

The service can't retrieve configuration information for the specified experiments.

While the service doesn't include this code in the response body, it's used in the message of an error response. If you encounter this error during a REST API request, it triggers a `503` response with the message "Failed to lookup tenant metadata".

<!-- document id=dee7c23dfdfca6da937ed1b45b3a73b5dc735719ee2897f103b823181f4705c8 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/experimentation-daily-summary-dmo.md -->

# Experimentation Daily Summary DMO

The Experimentation Daily Summary DMO captures the daily summary of personalization experiments.

## Object API Name

`ssot__AbnExperimentationDailySummary__dlm`

## Primary Key

Abn Experimentation Daily Summary Id (`Id__c`)

## All Fields

| Field Name                  | Field API Name                    | Description                                                                                           | Data Type |
| :-------------------------- | :-------------------------------- | :---------------------------------------------------------------------------------------------------- | :-------- |
| Experiment                  | `AbnExperimentId__c`              | The identifier for the experiment.                                                                    | text      |
| Experiment Cohort           | `AbnExperimentCohortId__c`        | The identifier for the cohort that's assigned to the experiment.                                      | text      |
| Metric Name                 | `MetricName__c`                   | The name of the engagement signal metric that the experiment measures.                                | text      |
| Metric Id                   | `MetricId__c`                     | The identifier for the engagement signal metric that the experiment measures.                         | text      |
| Metric Type                 | `ExperimentSummaryMetricType__c`  | The type of sngagement signal metric that the experiment measures.                                    | text      |
| Is Primary                  | `IsPrimary__c`                    | Indicates if the metric is a primary metric, which is used to determine the winner of the experiment. | boolean   |
| For Date                    | `ForDate__c`                      | The date when the summary was created.                                                                | date      |
| Last Updated Date Time      | `LastUpdatedDateTime__c`          | The date and time when the daily summary was last updated.                                            | dateTime  |
| Assigned Participants Count | `AssignedParticipantsCount__c`    | The number of participants assigned to the cohort on the day the daily summary was created.           | number    |
| Metric Value                | `MetricValueNumber__c`            | The metric value measured as part of the experiment.                                                  | number    |
| Signal Numerator Value      | `SignalNumeratorValueNumber__c`   | The numerator of `MetricValueNumber` if `ExperimentSummaryMetricType` is either RATE or AVG.          | number    |
| Signal Denominator Value    | `SignalDenominatorValueNumber__c` | The denominator of `MetricValueNumber` if `ExperimentSummaryMetricType` is either RATE or AVG.        | number    |

<!-- document id=e52f1e967821af6ec3ac12581dad21df0dabf3796f613b5655c5183ce24e4842 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/experimentation-log-dmo.md -->

# Experimentation Log DMO

The Experimentation Log Data Model Object (DMO) captures event data from personalization experiments.

## Object API Name

`ssot__AbnExperimentLog__dlm`

## Primary Key

Abn Experiment Log Id (`Id__c`)

## All Fields

| Field Name               | Field API Name                 | Description                                                                                                                                 | Data Type |
| :----------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ | :-------- |
| Personalization Point    | `PersonalizationPointId__c`    | The identifier for the personalization point.                                                                                               | text      |
| Personalization Decision | `PersonalizationDecisionId__c` | The identifier for the personalization decision.                                                                                            | text      |
| Personalization Id       | `PersonalizationId__c`         | The identifier for the personalized response sent to a specific personalization point.                                                      | text      |
| Request id               | `Requestid__c`                 | The identifier for the experimentation request sent to the experimentation pipeline.                                                        | text      |
| Request DateTime         | `RequestDateTime__c`           | The date and time the experimentation request was made.                                                                                     | dateTime  |
| Individual               | `Individualid__c`              | The identifier for the individual DMO.                                                                                                      | text      |
| Unified Individual       | `UnifiedIndividualId__c`       | The identifier for the unified individual.                                                                                                  | text      |
| Experiment               | `AbnExperimentId__c`           | The identifier for the experiment.                                                                                                          | text      |
| Experiment Cohort        | `AbnExperimentCohortId__c`     | The identifier for the cohort assigned to the experiment.                                                                                   | text      |
| Treatment Value          | `TreatmentValueText__c`        | The dynamic value populated based on the personalization type and experiment source.                                                        | text      |
| Pool Assignment          | `PoolAssignmentNumber__c`      | The pool a user is assigned to. A user is assigned to a cohort and a pool within the cohort when the user makes an experimentation request. | number    |
| Tracking Key             | `TrackingKeyText__c`           | The Global Unique Identifier (GUID) for tracking engagement events across Personalization API calls.                                        | text      |

<!-- document id=77ea06272ed33ca6cc2c80f094d220dbe8e2025f95c14c48134a9e71e175fd43 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/experimentation-summary-dmo.md -->

# Experimentation Summary DMO

The Experimentation Summary DMO captures the overall summary of personalization experiments.

## Object API Name

`ssot__AbnExperimentationSummary__dlm`

## Primary Key

Experimentation Summary ID (`Id__c`)

## All Fields

| Field Name                  | Field API Name                       | Description                                                                                                                                                                     | Data Type |
| :-------------------------- | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------- |
| Experiment                  | `AbnExperimentId__c`                 | The identifier for the experiment.                                                                                                                                              | text      |
| Experiment Cohort           | `AbnExperimentCohortId__c`           | The identifier for the cohort that's assigned to the experiment.                                                                                                                | text      |
| Metric Name                 | `MetricName__c`                      | The name of the engagement signal metric that the experiment measures.                                                                                                          | text      |
| Metric Id                   | `MetricId__c`                        | The identifier for the engagement signal metric that the experiment measures.                                                                                                   | text      |
| Experiment Analysis Status  | `ExperimentAnalysisStatus__c`        | The status of the experimentation data analysis.                                                                                                                                |           |
| Metric Type                 | `ExperimentSummaryMetricType__c`     | The type of engagement signal metric that the experiment measures.                                                                                                              | text      |
| Is Primary                  | `IsPrimary__c`                       | Indicates if the metric is a primary metric that's used to determine the winner of the experiment.                                                                              | boolean   |
| Last Updated Date Time      | `LastUpdatedDateTime__c`             | The date and time when the experiment summary was last updated.                                                                                                                 | dateTime  |
| Assigned Participants Count | `AssignedParticipantsCount__c`       | The number of participants assigned to the cohort that's assigned to the experiment.                                                                                            | number    |
| Metric Value                | `MetricValueNumber__c`               | The metric value measured as part of the experiment.                                                                                                                            | number    |
| Min Metric Value            | `MinMetricValueNumber__c`            | The lowest value of the metric recorded during the experiment.                                                                                                                  | number    |
| Max Metric Value            | `MaxMetricValueNumber__c`            | The highest value of the metric recorded during the experiment.                                                                                                                 | number    |
| Mean Metric Value           | `MeanMetricValueNumber__c`           | The average metric value recorded during the experiment.                                                                                                                        | number    |
| Variance                    | `VarianceNumber__c`                  | The statistical spread of metric values, calculated by taking the average of squared deviations from the mean.                                                                  | number    |
| Credible Interval Lower     | `CredibleIntervalLowerNumber__c`     | The lower value of the Bayesian credible interval. The credible interval is the range of the posterior distribution that contains the configured percentage of probable values. | number    |
| Credible Interval Upper     | `CredibleIntervalUpperNumber__c`     | The upper value of the Bayesian credible interval.                                                                                                                              | number    |
| Probability To Beat Control | `ProbabilityToBeatControlPercent__c` | The probability of the cohort for the measured metric to win against the control.                                                                                               | number    |
| Probability To Beat All     | `ProbabilityToBeatAllPercent__c`     | The probability of the cohort for the measured metric to win against all the other cohorts.                                                                                     | number    |
| Signal Numerator Value      | `SignalNumeratorValueNumber__c`      | The numerator of `MetricValueNumber` if `ExperimentSummaryMetricType` is either RATE or AVG.                                                                                    | number    |
| Signal Denominator Value    | `SignalDenominatorValueNumber__c`    | The denominator of `MetricValueNumber` if `ExperimentSummaryMetricType` is either RATE or AVG.                                                                                  | number    |

<!-- document id=e17280581405d70acf071c9d4569e93418dfaf7b42703094fed56738fd69b827 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/mobile-integration/configure-mobile-personalization/personalize-mobile-experiences-lowcode-flutter.md -->

# Flutter Low-Code Integration

Use the Salesforce Personalization Flutter plugin to display personalized banners, recommendations, and custom components in your Flutter app with minimal setup. The plugin bridges the native iOS and Android Personalization SDKs and provides a declarative `ContentZone` widget that handles fetching, rendering, and engagement tracking for you. Your app owns native SDK initialization, consent, trusted navigation, and accessible UI.

1. [Install the SDK](#install-the-sdk)
2. [Initialize the SDK](#initialize-the-sdk)
3. [Display a Content Zone](#display-a-content-zone)
4. [Out-of-the-Box Components](#out-of-the-box-components)
5. [Custom Components](#custom-components)
6. [Engagement Tracking](#engagement-tracking)
7. [Preview](#preview)
8. [Design-Time Rendering](#design-time-rendering)
9. [Identity and Events](#identity-and-events)

## Install the SDK

```shell
flutter pub add flutter_salesforce_personalization
```

Add the package. It resolves to the latest published version.

On iOS, the native pods are pulled in automatically the next time you build (or run `pod install`). On Android, you must also declare the Salesforce Maven repositories (see [Initialize the SDK](#initialize-the-sdk)).

### Requirements

| Requirement           | Reviewed baseline              |
| :-------------------- | :----------------------------- |
| Flutter               | 3.19 or later                  |
| Dart                  | 3.3 or later                   |
| Android               | API 26 minimum; compile SDK 37 |
| Java                  | 17                             |
| Kotlin Gradle plugin  | 2.3.0                          |
| Android Gradle Plugin | 8.13.2                         |
| Gradle wrapper        | 8.13                           |
| iOS deployment target | 15.0 or later                  |
| Swift                 | 5.7 or later                   |

Obtain these values from your Salesforce administrator and inject environment-specific values through the app's existing build-configuration or secret-management process. The samples show key names only.

| Key                        | Value                                 |
| :------------------------- | :------------------------------------ |
| `salesforce.cdp.appId`     | CDP application ID                    |
| `salesforce.cdp.endpoint`  | Bare endpoint host with no URL scheme |
| `salesforce.cdp.cdnUrl`    | CDN configuration URL                 |
| `salesforce.cdp.dataspace` | Dataspace, commonly `default`         |

## Initialize the SDK

The native SDKs must be initialized before any `ContentZone` widget attempts to fetch content. Initialization creates the connection to Data 360 (for identity and behavioral data) and the Personalization service (for content decisions). The Flutter plugin does not expose a Dart-side `configure(...)` call - the host app initializes the native SDK directly in platform code, ensuring it runs before the Flutter engine renders its first frame.

Complete both the Android and iOS platform setup below.

### Android setup

The plugin supplies native SDK dependencies transitively. The host app must provide the Salesforce Maven repositories and a compatible Android toolchain.

Use the reviewed plugins in `android/settings.gradle.kts`:

```kotlin
pluginManagement {
    val flutterSdkPath = run {
        val properties = java.util.Properties()
        file("local.properties").inputStream().use { properties.load(it) }
        requireNotNull(properties.getProperty("flutter.sdk")) {
            "flutter.sdk not set in local.properties"
        }
    }
    includeBuild("$flutterSdkPath/packages/flutter_tools/gradle")
    repositories { google(); mavenCentral(); gradlePluginPortal() }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_PROJECT)
    repositories { google(); mavenCentral() }
}

plugins {
    id("dev.flutter.flutter-plugin-loader") version "1.0.0"
    id("com.android.application") version "8.13.2" apply false
    id("org.jetbrains.kotlin.android") version "2.3.0" apply false
}

include(":app")
```

Use Gradle 8.13 in `android/gradle/wrapper/gradle-wrapper.properties`:

```
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-all.zip
```

Configure `android/app/build.gradle.kts`. Replace the sample namespace and application ID.

```kotlin
plugins {
    id("com.android.application")
    id("kotlin-android")
    id("dev.flutter.flutter-gradle-plugin")
}

repositories {
    google()
    mavenCentral()
    maven { url = uri("https://salesforce-marketingcloud.github.io/MarketingCloudSDK-Android/repository") }
    maven { url = uri("https://salesforce-marketingcloud.github.io/mobile-sdk-cdp-android/repository") }
    maven { url = uri("https://salesforce-marketingcloud.github.io/Personalization-Android/repository") }
}

android {
    namespace = "com.example.personalized_app"
    compileSdk = 37
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    defaultConfig {
        applicationId = "com.example.personalized_app"
        minSdk = 26
        targetSdk = flutter.targetSdkVersion
        versionCode = flutter.versionCode
        versionName = flutter.versionName
    }
}

kotlin {
    compilerOptions {
        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
    }
}

flutter { source = "../.." }
```

Do not add `com.salesforce.personalization:sdk` to app dependencies. The plugin exposes it transitively.

Declare `INTERNET` in the main manifest so release builds can reach the service. Register the custom Application and tenant metadata in `android/app/src/main/AndroidManifest.xml`. The custom preview scheme below is for controlled development devices only, use verified Android App Links for production preview tokens.

```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />
    <application
        android:name=".MainApplication"
        android:icon="@mipmap/ic_launcher"
        android:label="personalized_app">
        <meta-data android:name="salesforce.cdp.appId" android:value="YOUR_CDP_APP_ID" />
        <meta-data android:name="salesforce.cdp.endpoint" android:value="YOUR_CDP_ENDPOINT" />
        <meta-data android:name="salesforce.cdp.dataspace" android:value="default" />
        <meta-data android:name="salesforce.cdp.cdnUrl" android:value="YOUR_CDN_URL" />
        <activity
            android:name=".MainActivity"
            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
            android:exported="true"
            android:hardwareAccelerated="true"
            android:launchMode="singleTop"
            android:theme="@style/LaunchTheme"
            android:windowSoftInputMode="adjustResize">
            <meta-data android:name="io.flutter.embedding.android.NormalTheme" android:resource="@style/NormalTheme" />
            <meta-data android:name="flutter_deeplinking_enabled" android:value="false" />
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:host="preview" android:scheme="personalizationdemo" />
            </intent-filter>
        </activity>
        <meta-data android:name="flutterEmbedding" android:value="2" />
    </application>
</manifest>
```

Create `MainApplication.kt` (or use the existing with the initialization code) under the directory matching its package. This complete example deliberately leaves consent unset.

```kotlin
package com.example.personalized_app

import android.content.pm.PackageManager
import android.util.Log
import com.salesforce.marketingcloud.cdp.CdpConfig
import com.salesforce.marketingcloud.sfmcsdk.InitializationStatus
import com.salesforce.marketingcloud.sfmcsdk.SFMCSdk
import com.salesforce.marketingcloud.sfmcsdk.SFMCSdkModuleConfig
import com.salesforce.personalization.PersonalizationConfig
import io.flutter.app.FlutterApplication

class MainApplication : FlutterApplication() {
    override fun onCreate() {
        super.onCreate()
        val data = packageManager
            .getApplicationInfo(packageName, PackageManager.GET_META_DATA).metaData
        val appId = data.getString("salesforce.cdp.appId").orEmpty()
        val endpoint = data.getString("salesforce.cdp.endpoint").orEmpty()
        val dataspace = data.getString("salesforce.cdp.dataspace") ?: "default"
        val cdnUrl = data.getString("salesforce.cdp.cdnUrl")
        if (appId.isBlank() || appId.startsWith("YOUR_") ||
            endpoint.isBlank() || endpoint.startsWith("YOUR_")) {
            Log.w("PersonalizedApp", "Personalization is not configured; SDK init skipped")
            return
        }

        val cdp = CdpConfig.Builder(applicationContext, appId, endpoint)
            .trackScreens(false)
            .trackLifecycle(false)
            .sessionTimeout(1800L)
            .eventFlushRate(CdpConfig.EventFlushRate.QuantityAndInterval(10L, 5000L))
            .build()
        val personalization =
            PersonalizationConfig.Builder(applicationContext).dataspace(dataspace)
        if (!cdnUrl.isNullOrBlank() && !cdnUrl.startsWith("YOUR_")) {
            personalization.cdnUrl(cdnUrl)
        }

        SFMCSdk.configure(applicationContext, SFMCSdkModuleConfig.build {
            cdpModuleConfig = cdp
            personalizationModuleConfig = personalization.build()
        }) { status ->
            val message = if (status.status == InitializationStatus.SUCCESS) {
                "SDK ready; waiting for user consent"
            } else {
                "SDK initialization failed"
            }
            Log.d("PersonalizedApp", message)
        }
    }
}
```

### iOS setup

Set the deployment target to iOS 15 or later and use Swift 5.7 or later. The app target must use `use_frameworks!`. Flutter autolinking installs the native Salesforce pods; do not declare duplicate Salesforce pods manually.

Add the four `salesforce.cdp.*` keys inside the existing top-level dict in `ios/Runner/Info.plist`. The custom preview scheme is for controlled development devices only; use a verified Universal Link for production tokens:

```xml
<key>salesforce.cdp.appId</key>
<string>YOUR_CDP_APP_ID</string>
<key>salesforce.cdp.endpoint</key>
<string>YOUR_CDP_ENDPOINT</string>
<key>salesforce.cdp.dataspace</key>
<string>default</string>
<key>salesforce.cdp.cdnUrl</key>
<string>YOUR_CDN_URL</string>
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>com.example.personalized-app.preview</string>
        <key>CFBundleURLSchemes</key>
        <array><string>personalizationdemo</string></array>
    </dict>
</array>
<key>FlutterDeepLinkingEnabled</key>
<false/>
```

Initialize before registering Flutter plugins. This complete `ios/Runner/AppDelegate.swift` deliberately leaves consent unset:

```swift
import Flutter
import UIKit
import SFMCSDK
import Cdp
import Personalization

@main
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    initializePersonalizationSdk()
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: options)
  }

  override func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
  ) -> Bool { super.application(app, open: url, options: options) }

  override func application(
    _ application: UIApplication,
    continue activity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
  ) -> Bool {
    super.application(
      application,
      continue: activity,
      restorationHandler: restorationHandler
    )
  }

  private func initializePersonalizationSdk() {
    let info = Bundle.main.infoDictionary ?? [:]
    let appId = info["salesforce.cdp.appId"] as? String ?? ""
    let endpoint = info["salesforce.cdp.endpoint"] as? String ?? ""
    let dataspace = info["salesforce.cdp.dataspace"] as? String ?? "default"
    let cdnUrl = info["salesforce.cdp.cdnUrl"] as? String
    if appId.isEmpty || appId.hasPrefix("YOUR_") ||
       endpoint.isEmpty || endpoint.hasPrefix("YOUR_") {
      NSLog("Personalization is not configured; SDK init skipped")
      return
    }

    let cdp = CdpConfigBuilder(appId: appId, endpoint: endpoint)
    _ = cdp.trackScreens(false)
    _ = cdp.trackLifecycle(false)
    _ = cdp.sessionTimeout(1800)
    _ = cdp.eventFlushRate(
      EventFlushRateQuantityAndInterval(quantity: 10, interval: 5.0)
    )
    let personalization = PersonalizationConfigBuilder().dataspace(dataspace)
    if let cdnUrl, !cdnUrl.isEmpty, !cdnUrl.hasPrefix("YOUR_") {
      _ = personalization.cdnUrl(cdnUrl)
    }
    let config = ConfigBuilder()
      .setCdp(config: cdp.build())
      .setPersonalization(config: personalization.build())
      .build()
    SFMCSdk.initializeSdk(config) { statuses in
      let ready = !statuses.isEmpty && statuses.allSatisfy {
        $0.initStatus == .success
      }
      NSLog(ready ? "SDK ready; waiting for user consent" : "SDK initialization failed")
    }
  }
}
```

After the compatible Flutter package is published and added, confirm the Podfile target uses `platform :ios, '15.0'` and `use_frameworks!`, run CocoaPods, and open `Runner.xcworkspace`.

### Tips

- If the native SDK ends up off the classpath (Android) or the pods aren't linked (iOS), the plugin degrades gracefully - content zones render their `fallback` and status calls report "not ready" - instead of crashing.
- To enable debug logging during development: `await PersonalizationModule.setLogging(LogLevel.debug);`. Call this before the native `SFMCSdk.configure(...)` / `SFMCSdk.initializeSdk(...)` call in your platform init code, so logging is active for the whole init sequence. Disable before a production build.

## Display a Content Zone

With the SDK initialized and consent granted, place a `ContentZone` widget in your UI. Pass the content zone identifier and a list of components the zone is allowed to render.

After adding a ContentZone to your app code, create the matching content zone record in Salesforce Personalization. See [Set Up Mobile Content Zones](https://help.salesforce.com/s/articleView?id=mktg.persnl_experience_mobile_content_zones_register.htm) for instructions on defining personalization points, assigning components, and configuring engagement definitions.

Personalization must remain disabled until the user explicitly opts in. Await the Dart consent call and persist opt-in only after it succeeds. On opt-out, unmount live zones immediately, call the SDK, then persist the result. Changing consent does not make a mounted zone retry automatically; prefer mounting only while opted in, or refresh an attached controller after a successful change.

Recommendations are eager and not internally scrollable. Put a zone that can render recommendations in a host scrollable. All cards build at once, and built-in View is a mount/render event, not verified on-screen visibility.

The following illustrative widget focuses on update ordering and the required scrollable host. Its `loadChoice` and `saveChoice` callbacks are the app's awaited consent store; `null` means the user has not made a choice.

```dart
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter_salesforce_personalization/flutter_salesforce_personalization.dart';

Future<bool?> loadConsentChoice() async => null; // Replace with app storage.
Future<void> saveConsentChoice(bool value) async {} // Replace with app storage.

void main() => runApp(MaterialApp(home: HomeScreen(
  loadChoice: loadConsentChoice,
  saveChoice: saveConsentChoice,
)));

class HomeScreen extends StatefulWidget {
  const HomeScreen({
    super.key,
    required this.loadChoice,
    required this.saveChoice,
  });
  final Future<bool?> Function() loadChoice;
  final Future<void> Function(bool value) saveChoice;
  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  final _controller = ContentZoneController();
  late final List<Component> _components = <Component>[
    SalesforceBanner(onTap: _selectBanner),
    SalesforceRecommendations(onTap: _selectRecommendation),
  ];
  bool? _optedIn;
  bool _updating = false;

  @override
  void initState() { super.initState(); unawaited(_restoreConsent()); }

  Future<void> _restoreConsent() async {
    try {
      final saved = await widget.loadChoice();
      var nativeOptIn = await PersonalizationModule.isConsentOptIn();
      if (saved != true && nativeOptIn) {
        await PersonalizationModule.setConsent(optIn: false);
        nativeOptIn = false;
      }
      if (!mounted) return;
      setState(() => _optedIn = saved == true && nativeOptIn);
    } catch (_) {
      try { await PersonalizationModule.setConsent(optIn: false); } catch (_) {}
      if (mounted) {
        setState(() => _optedIn = false);
        _showSelection('Consent restoration failed');
      }
    }
  }

  void _selectBanner(SalesforceBannerModel model) =>
      _showSelection(model.header);
  void _selectRecommendation(SalesforceRecommendationTapEvent event) =>
      _showSelection(event.item.name);
  void _showSelection(String name) => ScaffoldMessenger.of(context)
      .showSnackBar(SnackBar(content: Text('Selected: $name')));

  Future<void> _setConsent(bool optIn) async {
    if (_updating) return;
    final previous = _optedIn;
    setState(() { _updating = true; if (!optIn) _optedIn = false; });
    try {
      await PersonalizationModule.setConsent(optIn: optIn);
      if (!mounted) return;
      setState(() => _optedIn = optIn);
      try {
        await widget.saveChoice(optIn);
      } catch (_) {
        if (optIn) {
          await PersonalizationModule.setConsent(optIn: false);
          if (mounted) setState(() => _optedIn = false);
        }
        if (mounted) _showSelection('Consent was applied but could not be saved');
      }
    } catch (_) {
      if (mounted) setState(() => _optedIn = previous);
      if (mounted) _showSelection('Consent update failed');
    } finally {
      if (mounted) setState(() => _updating = false);
    }
  }

  @override
  void dispose() { _controller.dispose(); super.dispose(); }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Personalized content')),
      body: RefreshIndicator(
        onRefresh: _optedIn == true ? _controller.refresh : () async {},
        child: ListView(
          physics: const AlwaysScrollableScrollPhysics(),
          padding: const EdgeInsets.all(16),
          children: <Widget>[
            Text(_optedIn == null
                ? 'Loading personalization choice'
                : _optedIn == true
                    ? 'Personalization is on'
                    : 'Personalization is off'),
            Wrap(spacing: 12, children: <Widget>[
              FilledButton(
                onPressed: _updating || _optedIn == null
                    ? null : () => unawaited(_setConsent(true)),
                child: const Text('Opt in'),
              ),
              OutlinedButton(
                onPressed: _updating || _optedIn == null
                    ? null : () => unawaited(_setConsent(false)),
                child: const Text('Opt out'),
              ),
            ]),
            if (_optedIn == true) ContentZone(
              name: 'HomeRecommendations',
              controller: _controller,
              allowedComponents: _components,
              loading: const CircularProgressIndicator(
                semanticsLabel: 'Loading personalized content',
              ),
              fallback: (_) => Semantics(
                liveRegion: true,
                child: const Text('Personalized content is unavailable.'),
              ),
            ),
          ],
        ),
      ),
    );
  }
}
```

### ContentZone Parameters

| Parameter                 | Contract                                                                                                               |
| :------------------------ | :--------------------------------------------------------------------------------------------------------------------- |
| `name`                    | Required content zone identifier. Use a unique identifier per simultaneously mounted zone.                             |
| `allowedComponents`       | Required lookup and security allowlist. Matching is case-insensitive; the first duplicate wins.                        |
| `loading`                 | Optional initial or explicit loading-state widget.                                                                     |
| `fallback`                | Optional bridge, timeout, validation, blocked component, consent, or empty-content fallback. Do not expose raw errors. |
| `timeoutMs`               | Native fetch timeout; default 10000 milliseconds.                                                                      |
| `controller`              | Optional programmatic refresh controller.                                                                              |
| `decisionsRequestContext` | Optional anchor and attributes merged with automatic context.                                                          |

The zone rebuilds its component allowlist whenever `allowedComponents` changes, comparing by value. Changing the allowed component names triggers a refetch; swapping only a component instance for an already-allowed name (for example a new style or `onTap`) re-renders in place from the retained serving with no refetch, reusing the same `ComponentContext` so a View is not re-fired. You no longer need to re-key or remount the zone to change the list, though keeping the set of names stable across rebuilds is still good practice.

Use `anchorType` in `DecisionsRequestContext`. `anchorDmoName` is deprecated and retained only as an alias. Attribute values must be `String`, `int`, `double`, or `bool`; convert dates to strings first.

### Refresh with a controller

`refresh()` keeps old content visible only while the request is pending. A failure replaces it with fallback; `refresh(withLoadingState: true)` shows loading while pending. Failures do not rethrow; inspect `lastRefreshError`. `dispose()` is currently a no-op but should still be called.

Create one `ContentZoneController` per simultaneously mounted zone. Binding is first-bind-wins and unbinding is ownership-aware, so disposing a second holder no longer unbinds the active zone - but a shared controller still drives only the zone that bound it first, so give each zone its own. Use separate controllers and `Future.wait` to refresh multiple zones.

App resume, connectivity recovery, identity changes, and `decisionsRequestContext` changes do not automatically fetch new content. After consent and identity are settled, refresh the dedicated zone controller once when the app's lifecycle policy requires a new decision.

## Out-of-the-Box Components

The plugin ships two ready-to-use components - `SalesforceBanner` and `SalesforceRecommendations` - that handle rendering and engagement tracking (`View` and `Click` events) automatically.

These components are available out-of-the-box in the UI and are registered under the names `"Salesforce_Banner"` and `"Salesforce_Recommendations"`.

### Banner contract

`SalesforceBanner` handles `Salesforce_Banner`. `header` is required and nonblank. `imageUrl` is supplied as a string; an invalid or blank value warns and renders an image fallback rather than rejecting an otherwise valid banner. `subheader`, `ctaText`, and `ctaUrl` are optional.

`ctaText` and `ctaUrl` are independent. A banner is actionable when an `onTap` callback exists or `ctaUrl` is nonblank. `onTap` wins. Label-only content can render without an action; URL-only content can be actionable without a visible CTA label. Prefer app-owned callbacks to enforce trusted destinations and accessible labels.

The reviewed built-in card uses a bare `GestureDetector`, provides no explicit button/link semantics or keyboard activation, and truncates text. Use a custom accessible component when those behaviors do not satisfy the app's accessibility requirements.

### Recommendations contract

`SalesforceRecommendations` handles `Salesforce_Recommendations`. Portrait uses one column and landscape uses two. It eagerly builds `Column` and `Row` trees; it does not provide a scroll view.

The model has optional `sectionHeader`, optional shared `ctaText`, and a nonempty list of valid items. Each item has nonblank `id` and `name`, an `imageUrl`, optional `description`, and optional item-level `url`. The plugin does not enforce unique IDs; production payloads must use unique IDs.

Invalid items are skipped, but engagement indices are not remapped. A skipped item can misattribute later View and Click events. Production responses must contain only valid items in unchanged flat serving order. Do not sort, filter, insert, or section before per-item tracking unless each original zero-based index is preserved.

### Styling contract

The reviewed renderer defaults are white backgrounds; 20sp semibold #393939 headers; 16sp #6B6B6B subheaders; 15sp underlined #0B5CAB CTAs; 28sp section headers; banner padding 12; recommendation card padding 20; spacing 12; image width fraction 0.3; maximum image size 150; and banner radius 8.

`SalesforceBannerStyle.ctaBackgroundColor` and `imageHeight` exist but are not consumed by the reviewed renderer.

## Custom Components

Implement a custom component to render a content zone with your own UI. A custom component can reuse an existing backend experience template (for example, clone `Salesforce_Banner`) or use a fully custom experience template name with its own fields.

Match the component's `name` to the backend experience template's component name. Validate the JSON payload in `validateAndCreateComponentModel`, and return the widget from `compose`. See [Engagement Tracking](#engagement-tracking) for reporting View and Click from a custom component.

## Engagement Tracking

Before engagement events are recorded, ensure your engagement definitions (View, Click) are configured in the Data 360 mobile connector. See [Set Up Mobile Engagement Tracking](https://help.salesforce.com/s/articleView?id=mktg.persnl_experience_mobile_engagement_tracking.htm) for instructions on defining engagement actions alongside your components and content zones.

Out-of-the-box components track `View` and `Click` automatically. These are the only two actions currently supported end-to-end. The engagement lifecycle for both built-in and custom components:

- Built-in Banner invokes its view-once tracker on mount and when `personalizationId` changes while its widget state remains alive.
- Built-in Recommendations invokes the per-item view-once tracker for every eagerly rendered index. Item `id` is not part of the dedup key, and this is not on-screen visibility.
- A tracker invocation emits only when the expected engagement payload shape contains a matching View payload. A no-op still consumes its once/PID gate.
- A silent same-ID refresh does not refire while the child state survives. `refresh(withLoadingState: true)` can refire at the same ID after a loading frame disposes and remounts the child state.
- A fully disposed and remounted zone can attempt View again at the same ID.
- Every successful fetch creates a new `ComponentContext`, but its ID can remain unchanged. Context identity and `personalizationId` are different signals.
- On an actionable tap, built-in components invoke Click tracking before the callback or URL action. The action proceeds regardless of payload availability; analytics emit only when a matching payload exists. URL-free cards in the reviewed renderer still install a no-op gesture recognizer.
- Shape and count mismatches are logged but do not block rendering.
- Preview commonly has no engagement payloads and is not evidence that production analytics will be emitted.

For custom components:

- For custom single elements, use `trackEngagementViewOnce()` for build/mount View and `trackEngagement()` for repeatable actions.
- For custom lists, use the per-item variants with original serving indices.
- View-once methods deduplicate by the exact `ComponentContext` object. Pass the context supplied by the zone; do not construct or copy one.
- For true impression measurement, use a custom lazy or paged component and report from an actual visibility signal.

## Preview

Preview is per zone. A valid receipt causes only its matching zone to refetch; other active zones are unaffected. Query with `PersonalizationModule.isPreview(exactZoneName)`. The plugin's border is not an accessible status indicator by itself; also show persistent Preview text and Flutter semantics.

The reviewed API exposes only a one-shot preview query, not an observable per-zone preview state for host UI. A persistent synchronized accessible label therefore requires a plugin API or built-in renderer change and remains a publication gate.

Add the separately versioned deep-link dependency validated for the release:

```shell
flutter pub add app_links:^6.4.0
```

Use `app_links` for cold and warm links. Register only endpoints your app validates. For HTTPS, configure verified Android App Links and iOS Universal Links for a domain you control. This complete handler awaits the cold link and subscribes for warm links:

```dart
import 'dart:async';
import 'package:app_links/app_links.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter_salesforce_personalization/flutter_salesforce_personalization.dart';

class PreviewLinks {
  PreviewLinks._(this._subscription);
  final StreamSubscription<Uri> _subscription;

  static Future<PreviewLinks> start() async {
    final links = AppLinks();
    final seen = <String>{};
    Future<void> forwardOnce(Uri uri) async {
      if (seen.add(uri.toString())) await _forward(uri);
    }
    final subscription = links.uriLinkStream.listen(
      (uri) => unawaited(forwardOnce(uri)),
      onError: (_) => debugPrint('A preview link could not be read.'),
    );
    final initial = await links.getInitialLink();
    if (initial != null) await forwardOnce(initial);
    return PreviewLinks._(subscription);
  }

  static Future<void> _forward(Uri uri) async {
    if (!_trusted(uri)) return;
    try {
      await PersonalizationModule.handlePreviewUrl(uri.toString());
    } catch (_) {
      debugPrint('A trusted preview link could not be applied.');
    }
  }

  static bool _trusted(Uri uri) {
    final custom = uri.scheme == 'personalizationdemo' &&
        uri.host == 'preview' && (uri.path.isEmpty || uri.path == '/') &&
        !uri.hasPort;
    final https = uri.scheme == 'https' &&
        uri.host == 'preview.example.com' &&
        uri.path == '/mobile-personalization' &&
        (!uri.hasPort || uri.port == 443);
    final token = uri.queryParametersAll['sfp-preview'];
    final exactQuery = uri.queryParametersAll.length == 1 &&
        token != null && token.length == 1 && token.single.trim().isNotEmpty;
    return (custom || https) && uri.userInfo.isEmpty &&
        uri.fragment.isEmpty && exactQuery;
  }

  Future<void> dispose() => _subscription.cancel();
}
```

Await `PreviewLinks.start()` before mounting zones, retain the returned owner, and dispose it at app teardown. Treat the full URL and token as sensitive bearer-like material. Never log, persist, analyze, or include them in crashes or support artifacts. Reject untrusted schemes, hosts, paths, ports, user info, fragments, extra query keys, duplicate tokens, and empty tokens.

## Design-Time Rendering

`MockDataContentZone<T>` renders components with mock data for styling and layout without any backend setup or networking. It is development/test-only. It accepts one matching `Component<T>`, `MockContent.success(model)` or `MockContent.failure(error)`, `loading`, `fallback`, `mockLoadingMs`, and an optional controller. Mock refresh always reruns loading then resolution. Keep component and mock objects stable rather than recreating them on every parent rebuild.

Use a mock controller to exercise refresh and `MockContent.failure` to verify a customer-safe fallback. Never ship a mock zone in production.

```dart
import 'package:flutter/material.dart';
import 'package:flutter_salesforce_personalization/flutter_salesforce_personalization.dart';

class BannerMockPreview extends StatefulWidget {
  const BannerMockPreview({super.key});
  @override
  State<BannerMockPreview> createState() => _BannerMockPreviewState();
}

class _BannerMockPreviewState extends State<BannerMockPreview> {
  final _controller = ContentZoneController();
  final _component = SalesforceBanner();
  late final _success = MockContent<SalesforceBannerModel>.success(
    SalesforceBannerModel(
      header: 'Sample offer',
      imageUrl: 'https://images.example.com/sample-offer.png',
    ),
  );
  late final _failure =
      const MockContent<SalesforceBannerModel>.failure('Design-time failure');
  bool _fail = false;
  @override
  void dispose() { _controller.dispose(); super.dispose(); }
  @override
  Widget build(BuildContext context) {
    return Column(children: <Widget>[
      MockDataContentZone<SalesforceBannerModel>(
        name: 'banner-preview',
        component: _component,
        mockContent: _fail ? _failure : _success,
        controller: _controller,
        mockLoadingMs: 200,
        loading: const CircularProgressIndicator(),
        fallback: (_) => const Text('Preview content is unavailable.'),
      ),
      Wrap(spacing: 8, children: [
        FilledButton(
          onPressed: () => setState(() => _fail = false),
          child: const Text('Show content'),
        ),
        OutlinedButton(
          onPressed: () => setState(() => _fail = true),
          child: const Text('Show fallback'),
        ),
        OutlinedButton(
          onPressed: _controller.refresh,
          child: const Text('Refresh mock'),
        ),
      ]),
    ]);
  }
}
```

## Identity and Events

Identity setters and getters are available after native initialization, explicit opt-in, and app authentication:

```dart
import 'package:flutter_salesforce_personalization/flutter_salesforce_personalization.dart';

Future<void> updateAndReadIdentity() async {
  await PersonalizationModule.setProfileId('customer-123');
  await PersonalizationModule.setAttributes(<String, String>{'tier': 'gold'});
  await PersonalizationModule.setPartyIdentificationName('Customer ID');
  await PersonalizationModule.setPartyIdentificationNumber('customer-123');
  await PersonalizationModule.setPartyIdentificationType('CRM');
  final String? profileId = await PersonalizationModule.getProfileId();
  final Map<String, String>? attributes = await PersonalizationModule.getAttributes();
  final String? name = await PersonalizationModule.getPartyIdentificationName();
  final String? number = await PersonalizationModule.getPartyIdentificationNumber();
  final String? type = await PersonalizationModule.getPartyIdentificationType();
  if ([profileId, attributes, name, number, type].contains(null)) {
    throw StateError('Identity was not fully available');
  }
}
```

`setAttributes` upserts supplied keys and leaves other keys unchanged. Use `clearAttribute` or `clearAllAttributes` for attributes. Those methods do not clear `profileId` or party-identification fields, and this plugin version exposes no public API that clears them. Do not set those identifiers in a multi-user app until the compatible release documents a supported native identity/session reset. Track behavioral events only after the same consent and governance checks.

**note:** **Mobile backend prerequisite:** A mobile personalization point matching `ContentZone.name`, an assigned component or experience template (built-in names are `Salesforce_Banner` and `Salesforce_Recommendations`), payloads that satisfy the contracts above, and View/Click engagement definitions must all be configured and activated in the backend before a zone can return content. See [Set Up Mobile Content Zones](https://help.salesforce.com/s/articleView?id=mktg.persnl_experience_mobile_content_zones_register.htm).

<!-- document id=42e6ffa147d4747a4caede1ec5ee42582e6fa6a0268dbf1b932f64ef8723c62e url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/invocable-actions/get-personalization-decision-invocable-action-reference.md -->

# Get Personalization Decisions Invocable Action

Retrieves personalized recommendations from Salesforce Personalization for the specified context and personalization point.

This action is available in API version 63.0 and later.

## Special Access Rules

The Get Personalization Decisions action is available in Salesforce orgs with the Personalization license. For more information on Personalization permissions, see [Set Up Salesforce Personalization User Permissions](https://help.salesforce.com/s/articleView?id=mktg.persnl_setup_permission_set_create.htm).

## Supported REST HTTP Methods

- URI

  - : `/services/data/v63.0/actions/standard/getPersonalizationDecisions`

- Formats

  - : JSON, XML

- HTTP Methods

  - : `POST`

- Authentication

  - : `Authorization: Bearer token`

## Inputs

| Input Parameter                                       | Type             | Required? | Description                                                                                                                                                                                                                                                                                                                                                                   |
| :---------------------------------------------------- | :--------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `persnlDecisionInputRepresentation`                   | Apex-defined     | Yes       | An Apex input representation record that contains context and personalization point details for retrieving a personalization decision.                                                                                                                                                                                                                                        |
| `persnlDecisionContextInputRepresentation`            | Apex-defined     | Yes       | An Apex input representation record record that contains details about an individual’s context and the anchor used by Personalization to exclude specific content from recommendations and recommend similar content.                                                                                                                                                         |
| `persnlPointInputRepresentation`                      | Array of objects | Yes       | A collection of Apex input representation records that contain details about personalization points.                                                                                                                                                                                                                                                                          |
| `individualId`                                        | String           | Yes       | The ID of the individual to retrieve a personalization decision for.                                                                                                                                                                                                                                                                                                          |
| `unifiedIndividualId`                                 | String           | No        | An optional unified ID that associates an individual to a Data Cloud Unified Profile. This ID ensures consistent experimentation cohort assignments for all interactions, even if a user has different individual IDs across channels. Without this ID, a user can end up in different cohorts across channels. Use `unifiedIndividualId` for experimentation-only use cases. |
| `dataSpace`                                           | String           | No        | The data space in Data Cloud that establishes the logical partition within which the personalization context exists.                                                                                                                                                                                                                                                          |
| `anchorId`                                            | String           | No        | A unique ID to be used by Personalization to reference content that the end user is interacting with. This ID helps Personalization stop this content from being recommended. It also lets you suggest more relevant suggestions based on your targeting rules and the filtering rules you set for recommenders.                                                              |
| `anchorType`                                          | String           | No        | The API name of the source Data Model Object that contains content that the end user is interacting with.                                                                                                                                                                                                                                                                     |
| `persnlPointId`                                       | String           | No        | The ID of a personalization point. This value is optional if you specify the name of a personalization point.                                                                                                                                                                                                                                                                 |
| `persnlPointName`                                     | String           | No        | The API name of a personalization point. This value is optional if you specify the ID of a personalization point.                                                                                                                                                                                                                                                             |
| `dynamicContextVariables`                             | Array of objects | No        | A list of field-value pairs used to pass dynamic filters, such as category, price, and brand to filter recommendations. Each object in the list must have a `field` (string) and a `value` (string).                                                                                                                                                                          |
| `persnlRecommenderDynamicVariableInputRepresentation` | Apex-defined     | No        | An Apex input representation record that contains a dynamic filter field and value for personalized recommendations.                                                                                                                                                                                                                                                          |
| `decisionId`                                          | String           | No        | Optional. The ID of a specific decision to return without rule evaluation. You can specify the decisionId to test whether the Salesforce Personalization Decisioning API returns a particular decision.                                                                                                                                                                       |
| `invocationType`                                      | String           | Yes       | The type of invocation used for configuring the output response format. Accepted values for use in Flow are `FLOW` and `FLOW_JSON`.                                                                                                                                                                                                                                           |

## Outputs

| Output Parameter                            | Description                                                                                                                                                                        |
| :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `persnlData`                                | A JSON string containing personalized recommendations.                                                                                                                             |
| `persnlFieldRepresentation`                 | The DMO field representation.                                                                                                                                                      |
| `field`                                     | The API name of the field.                                                                                                                                                         |
| `value`                                     | The value associated with the field.                                                                                                                                               |
| `additionalFields`                          | A list of field and value pairs from the personalization recommendation matching the expected schema of the personalization point.                                                 |
| `persnlAttributeRepresentation`             | The content attributes to be returned as configured on the personalization decision                                                                                                |
| `attributeName`                             | The name of the attribute.                                                                                                                                                         |
| `attributeValue`                            | The value associated with the attribute.                                                                                                                                           |
| `contentAttributes`                         | Content attributes returned in the personalized decision response as configured in the personalization schema.                                                                     |
| `persnlDecisionOutputRepresentation`        | An Apex output representation record that contains details about personalized recommendations, associated data, and diagnostic information.                                        |
| `persnlRepresentation`                      | An Apex output representation record containing personalized recommendations received from Personalization.                                                                        |
| `persnlRecommendationsOutputRepresentation` | An Apex output representation record that contains details about personalized recommendations data, including structured content objects that align with a personalization schema. |
| `persnlDiagnosticsRepresentation`           | An Apex output representation record that contains diagnostic information related to the personalization request.                                                                  |
| `persnlPointId`                             | The ID of the personalization point used in the request.                                                                                                                           |
| `persnlPointName`                           | The name of the personalization point used in this request.                                                                                                                        |
| `persnlRecommendations`                     | An array of personalized content objects matching the expected schema of the personalization point.                                                                                |
| `persnlContentId`                           | The ID of a Personalization Content Record.                                                                                                                                        |
| `diagnostics`                               | Diagnostic information about the request, aiding in analysis and troubleshooting.                                                                                                  |
| `diagnosticsCode`                           | A diagnostics code tied to the request’s processing or outcome.                                                                                                                    |
| `diagnosticsDescription`                    | A detailed message offering context and insights related to the diagnostics code.                                                                                                  |
| `requestId`                                 | A unique ID for the request and its corresponding response.                                                                                                                        |

## Example Request

```json
{
  "inputs": [
    {
      "persnlDecisionInputRepresentation": {
        "context": {
          "individualId": "e507e3f935a9b6ec9cbba5b77728f44f",
          "dynamicContextVariables": [
            {
              "field": "category",
              "value": "shoes"
            },
            {
              "field": "brand",
              "value": "NTO Retail"
            },
            {
              "field": "price",
              "value": "100"
            }
          ]
        },
        "personalizationPoints": [
          {
            "persnlPointName": "Product Recommendations"
          }
        ]
      }
    }
  ]
}
```

## Example Response

```json
{
  "PersnlDecisionOutputRepresentation": {
    "personalizations": [
      {
        "personalizationId": "3b8a600b-5e29-4d62-b90b-76950a5bc9db",
        "persnlPointId": "9ppSB00000010PNYAY",
        "persnlPointName": "Shoes",
        "persnlRecommendations": [
          {
            "personalizationContentId": "3b8a600b-5e29-4d62-b90b-76950a5bc9db:1",
            "additionalProperties": [
              "PurchaseUrl__c:https://www.northerntrailoutfitters.com/default/men%E2%80%99s-renew-leather-boots-1050073AOZ.html",
              "ssot__PrimaryProductCategory__c:Shoes",
              "ssot__Name__c:Men’s Renew Leather Boots",
              "ssot__BrandId__c:NTO",
              "ssot__ProductSKU__c:1050073AOZ"
            ],
            "additionalFields": [
              {
                "name": "PurchaseUrl__c",
                "value": "https://www.northerntrailoutfitters.com/default/men%E2%80%99s-renew-leather-boots-1050073AOZ.html"
              },
              {
                "name": "ssot__PrimaryProductCategory__c",
                "value": "Shoes"
              },
              {
                "name": "ssot__Name__c",
                "value": "Men’s Renew Leather Boots"
              },
              {
                "name": "ssot__BrandId__c",
                "value": "NTO"
              },
              {
                "name": "ssot__ProductSKU__c",
                "value": "1050073AOZ"
              }
            ]
          }
        ],
        "attributes": null,
        "contentAttributes": [
          {
            "eTag": null,
            "weakEtag": 0,
            "attributeName": "IntroductionText",
            "attributeValue": "Recommended for you"
          }
        ],
        "diagnostics": []
      }
    ],
    "diagnostics": [],
    "requestId": "4d224906-d4a8-409d-b4d4-fc981d1e4024"
  }
}
```

<!-- document id=0448f48900b0cbce48793491df721615d4837270a7ab51b891e9dcb52745e733 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/web-integration/configure-web-personalization/initialize-einstein-personalization-module.md -->

# Initialize the Personalization Module

To use the Personalization module, you must initialize it at the beginning of your sitemap. Initialize the module using the `SalesforceInteractions.Personalization.Config.initialize` method, as shown in this example.

```javascript
SalesforceInteractions.Personalization.Config.initialize({
  personalizationExperienceConfigs: [YOUR_PERSONALIZATION_EXPERIENCES],
  customFlickerDefenseConfig: [CUSTOM_FLICKER_DEFENDER_CONFIGURATION],
  customEngagementConfig: [CUSTOM_ENGAGEMENT_DESTINATIONS_CONFIGURATIONS],
});
```

**important:** Since the module initialization must occur before the sitemap is initialized, you must call the `SalesforceInteractions.Personalization.Config.initialize` method before you call `SalesforceInteractions.init`.

The `SalesforceInteractions.Personalization.Config.initialize` method accepts the objects described in this table.

| Object                             | Type  | Description                                                                                                                        |
| ---------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `personalizationExperienceConfigs` | Array | Optional. Specify personalization experiences to be included in the configuration.                                                 |
| `customFlickerDefenseConfig`       | Array | Optional. Configure flicker defense mechanisms used to prevent content flicker when retrieving and rendering personalized content. |
| `customEngagementConfig`           | Array | Optional. Define custom destinations to send engagement data.                                                                      |

<!-- document id=4ad242d33dc85d789f5b289dd2719cc58e31a2d60c9bcafbbdd0732b494f939c url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/web-integration/integrate-personalization-modern-frontend-frameworks.md -->

# Integrate Salesforce Personalization with Frontend Frameworks

Seamlessly integrate Salesforce Personalization into frontend frameworks such as React, Vue, Angular, and others using a component-based approach. With this approach, you can create custom components that register themselves as content zones, ensuring robust, reliable delivery and rendering of personalized content.

Traditional DOM manipulation by the SDK can conflict with the virtual DOM or rendering strategies of modern frameworks, causing personalized content to disappear. By creating a custom component that registers itself as a content zone handler, you make sure that personalized content is delivered and rendered using your framework's own methods. This approach works well for any component-based frontend architecture.

## Key Concepts

- Web Personalization Manager (WPM)

  - : The UI for previewing and managing personalized content zones.

- Content Zone Handler

  - : A registration for a specific area or component in your app that can be personalized. Use the Personalization module's `Config.ContentZoneHandler.set` function to register your handler, providing a unique name and configuration object.

## Register a Content Zone Handler

To enable personalization, register each content zone handler using the `set` function. This function ensures that your content zone is recognized by the Personalization module and can be targeted for dynamic content replacement.

```js
SalesforceInteractions.Personalization.Config.ContentZoneHandler.set(
  (ContentZoneHandlerName: String), // For example, "home_banner"
  (ContentZoneHandlerProperties: Object),
);
```

This table describes the parameters required by the `set` function:

| Parameter                      | Type   | Required | Description                                                                              |
| ------------------------------ | ------ | -------- | ---------------------------------------------------------------------------------------- |
| `ContentZoneHandlerName`       | String | Yes      | Unique, machine-friendly name for the content zone handler (for example, `home_banner`). |
| `ContentZoneHandlerProperties` | Object | Yes      | Configuration object defining how the content zone behaves and is rendered.              |

### ContentZoneHandlerProperties Interface

The `ContentZoneHandlerProperties` interface defines the configuration object used when registering a content zone handler.

```ts
interface ContentZoneHandlerProperties {
  onReady: (content: string, metadata: ContentZoneHandlerMetadata) => void;
  onRevert?: (metadata: ContentZoneHandlerMetadata) => void;
  onHighlight?: (highlight: boolean, metadata?: ContentZoneHandlerMetadata) => void;
  path?: string;
  label?: string;
}
```

| Property      | Required?           | Description                                                                                                                                                                                                                                                                                              |
| ------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onReady`     | Yes                 | `onReady` is called when personalized content is ready for rendering. This property receives personalized content from Personalization as an input parameter and enables you to define custom rendering logic inside your component.                                                                     |
| `onRevert`    | No, but recommended | Used only at design time (not at runtime). `onRevert` is called when a preview is cancelled in WPM. When a business user cancels a preview in WPM, your page must revert to rendering the original, non-personalized content of the page.                                                                |
| `label`       | No                  | User-friendly name of the registered content zone handler that appears within WPM. If not provided, this property defaults to showing the handler name.                                                                                                                                                  |
| `path`        | No                  | Used only at design time (not at runtime). Specifies a CSS selector that WPM uses to visually highlight the content zone handler in the page editor. This helps business users easily locate and identify the content zone handler’s position on the page when setting up personalization experiences.   |
| `onHighlight` | No                  | Used only at design time (not at runtime). Custom logic for WPM to visually highlight the content zone handler. Use `onHighlight` only if you can't use the `path` property. For example, when your component uses Shadow DOM or other advanced rendering techniques that make CSS selectors unreliable. |
|               |

**important:** Don't define both `path` and `onHighlight` at the same time.

### Example: Personalization Content Handler using Vanilla JavaScript

Here's an example that demonstrates how to implement a content zone handler using vanilla JavaScript:

```html
<div id="hero_banner_element"></div>

<script type="text/javascript">
  window.SalesforceInteractions.Personalization.Config.ContentZoneHandler.set(
    /** Define the content zone name */
    "hero_banner",

    /** Define the content zone configuration */
    {
      /** Optionally define a content zone label that will be displayed in the UI */
      label: "Hero Banner",

      /** Optionally specify a CSS selector for the content zone. 
                It will be used to highlight the content zone on the page in WPM */
      path: "#hero_banner_element",

      /** Set onReady function to render personalized content on the page.
                Define any custom logic here */
      onReady: (content) => {
        document.querySelector("#hero_banner_element").innerHTML = content;
      },

      /** Optionally revert content to its original state. */
      onRevert: () => {
        document.querySelector("#hero_banner_element").innerHTML = "";
      },
    },
  );
</script>
```

### Example: Personalization Content Handler React Component

Here's an example that demonstrates how to implement a custom content handler component in React. This component registers itself as a content zone handler and manages the rendering of personalized content:

```jsx
import React, { useEffect, useState } from "react";

export const PersonalizationContentHandler = ({ children, contentZoneName, contentZoneLabel }) => {
  /** Define state variable for Personalized Content */
  const [personalizedContent, setPersonalizedContent] = useState(undefined);
  /** Define state variable for your component's elementId the unique CSS selector */
  const [elementId, setElementId] = useState(undefined);
  /** Initialize the component */
  useEffect(() => {
    /** Generate elementId for the unique CSS selector */
    setElementId(`__sf_personalization_contentzonehandler_${contentZoneName}`);
    /** Register Content Zone Handler */
    window.SalesforceInteractions.Personalization.Config.ContentZoneHandler.set(
      /** Use content zone name from an attribute of the component */
      contentZoneName,
      {
        /** Use content zone label from an attribute of the component */
        label: contentZoneLabel,
        /** Generate a unique CSS selector for the component based on the generated elementId */
        path: `#${elementId}`,
        /** Set onReady function. 'handleReady' function is defined below */
        onReady: handleReady,
        /** Set onRevert function. */
        onRevert: () => {
          /** Reset the value of the 'personalizedContent' state variable  */
          setPersonalizedContent(undefined);
        },
      },
    );
    return () => {
      /** Deregister content zone handler at cleanup */
      window.SalesforceInteractions.Personalization.Config.ContentZoneHandler.set(contentZoneName, {
        onReady: () => {},
      });
    };
  });
  const handleReady = (content) => {
    /** Assign personalized content returned by Personalization to the 'personalizedContent' state variable */
    setPersonalizedContent(content);
  };
  /** Render personalized content, if available  */
  /** Content is wrapped with a DIV that has a unique ID attribute */
  if (personalizedContent) {
    return <div id={elementId} dangerouslySetInnerHTML={{ __html: personalizedContent }} />;
  } else {
    /** Render original content if personalized content is not available  */
    /** Content is wrapped with a DIV that has a unique ID attribute */
    return <div id={elementId}>{children}</div>;
  }
};
```

Here's how you can use the custom content handler component in your application.

```jsx
<PersonalizationContentHandler contentZoneName="ProductRecs" contentZoneLabel="Product Recs">
  <h1>Non-personalized content</h1>
  <p>This content will be replaced with Personalized Content</p>
</PersonalizationContentHandler>
```

## Best Practices

- Each content zone handler must have a unique, machine-friendly name.
- Implement `onRevert` for proper WPM preview/cancel support.
- Use `path` for simple highlight scenarios; use `onHighlight` for advanced or Shadow DOM cases.
- The `onReady` callback must render the personalized content. If not set, show the original children.
- Unregister or reset handlers on component unmount if needed.
- The `label` property makes the handler user-friendly in WPM.

## Troubleshooting

- If personalized content disappears, ensure you are not manipulating the DOM outside React.
- If preview cancel in WPM does not work, implement `onRevert`.
- If WPM cannot highlight your zone, check your `path` or implement `onHighlight`.

## See Also

- [Personalize Web Experiences](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-web-experiences.md)
- [Integrate the Salesforce Interactions SDK](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/integrate-salesforce-interactions-sdk.md)
- [Example Sitemap](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/example-sitemap.md)

<!-- document id=87ff7927ad7d1a36ce1fbd63fa1e8f1dac4e64434d176e822143a68760abdf6b url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/web-integration/integrate-salesforce-interactions-sdk.md -->

# Integrate the Salesforce Interactions SDK

To integrate the Salesforce Interactions SDK with your website and enable personalization capabilities:

1. [Create a data space](#create-a-data-space)
2. [Create a website connector](#create-a-website-connector)
3. [Upload your event schema](#upload-your-event-schema)
4. [Install the Interactions SDK on your website](#install-the-interactions-sdk-on-your-website)
5. [Create and upload a sitemap](#create-and-upload-a-sitemap)
6. [Create a website data stream](#create-a-website-data-stream)
7. [Map website connector object fields](#map-website-connector-object-fields)

## Create a Data Space

You can connect Personalization to any data space, including the default data space that’s provided when you install Data Cloud. Until you create additional data spaces, all Data Cloud objects are mapped to the default data space.

To segregate your brand, region, or department data and services, create additional data spaces. To create more data spaces, you need the Data Spaces add-on license.

To create a data space, perform these steps.

1. Go to Data Cloud Setup.
2. Under Data Management, click **Data Spaces**.
3. Click **New**, and give the data space a unique name.
4. Enter a unique data space prefix, starting with a letter and including up to three alphanumeric characters.

   **note:** After you save the data space, you can’t change its prefix because it becomes part of the API name used to differentiate objects that exist in multiple data spaces.

5. Add an optional description about the purpose of the data space.
6. Click **Save**.

**See Also**

- _Salesforce Help_: [Manage Data Spaces](https://help.salesforce.com/s/articleView?id=sf.c360_a_data_spaces.htm)
- _Salesforce Help_: [Create a Data Space](https://help.salesforce.com/s/articleView?id=sf.c360_a_data_spaces_create.htm)

## Create a Website Connector

To capture website data and control the scope of data ingestion, connect your website to Data Cloud by creating a website connector.

1. Go to Data Cloud Setup.
2. Under CONFIGURATION, click **Websites & Mobile Apps**.
3. Click **New**.
4. Provide a **Connector Name**.
5. From the Connector Type dropdown, select **Website** and click **Save**.

## Upload Your Event Schema

With Interactions SDK, you can track various types of interactions on your website, with each interaction capturing a specific set of data. When setting up a website connector to send this data to Data Cloud, you must upload a schema file in JSON format that outlines the structure of the event data you’re tracking.

The SDK provides a recommended schema file that covers common events such as adding items to a cart or viewing an item in a product catalog. This recommended schema includes mappings for:

- Engagement Events
  - Cart Interaction Mapping
  - Catalog Interaction Mapping
  - Order Interaction Mapping
  - Consent Event Mapping
- Profile Events
  - Contact Point Email Mapping
  - Contact Point Phone Mapping
  - Identity Mapping
  - Party Identification Mapping

To use the power of the unified event model, we suggest using the recommended schema. Alternatively, you can upload your own custom schema. Once uploaded, each interaction type appears as an object with corresponding attributes.

1. [Download the recommended schema file](https://cdn.c360a.salesforce.com/cdp/schemas/250/web-connector-schema.json) or use your own custom schema file.
2. To upload the schema file, click **Upload Schema** under the Schema block.
3. Confirm that all events and their associated fields are populated correctly.
4. Click **Save**.

After you upload the schema, examine it for accuracy.

1. To change your schema at any point, click **Update Schema**.

   **important:** You can only add new events and fields. The schema must retain all previous events and fields.

2. To update your schema, click **Yes, Update**.
3. To view the full schema you uploaded, click **View Full Schema**.

**See Also**

- _Download_: [Recommended Web Connector Schema (JSON)](https://cdn.c360a.salesforce.com/cdp/schemas/250/web-connector-schema.json)

## Install the Interactions SDK On Your Website

After you’ve created a connector for your website and configured your event schema, you can install the Interactions SDK on your website.

1. Scroll down to the Integration Guide section of the website connector setup page.
2. Copy the Content Delivery Network (CDN) URL.
3. Add the script to the `<head>` section of your website’s code using a `<script>` tag.
4. Initialize the SDK using the `SalesforceInteractions.init` method, as described in the [Initialization](https://developer.salesforce.com/docs/atlas.en-us.c360a_api.meta/c360a_api/c360a_api_initialization.htm) section of the Salesforce Interactions SDK documentation.

**See Also**

- [Capture Web Interactions](https://developer.salesforce.com/docs/atlas.en-us.c360a_api.meta/c360a_api/c360a_api_salesforce_interactions_web_sdk.htm)
- [Initialization](https://developer.salesforce.com/docs/atlas.en-us.c360a_api.meta/c360a_api/c360a_api_initialization.htm)
- [Consent](https://developer.salesforce.com/docs/atlas.en-us.c360a_api.meta/c360a_api/c360a_api_consent.htm)

## Create and Upload a Sitemap

The Web SDK sitemap is a JavaScript file that outlines the data capture logic across different pages of your website, based on which the SDK captures user interactions from your website during site navigation.

To create and upload a sitemap, perform these steps.

1. Install the [Salesforce Interactions SDK Launcher Chrome extension](https://chromewebstore.google.com/detail/salesforce-interactions-s/mhmpepeohaddbhkhecaldflljggicedf).
2. Enable and access the Sitemap Editor on your website through the extension.
3. Use the Sitemap Editor to instrument your website’s sitemap.
4. Create a JavaScript file named `sitemap.js`.
5. Copy the sitemap code you created and paste it into this file.
6. Navigate to the Sitemap section of the website connector setup page.
7. Click **Upload** and upload the `sitemap.js` file you created.
8. Review the sitemap for errors, and click **Save**.

For more information about Interactions SDK sitemaps, see the [Sitemap](https://developer.salesforce.com/docs/atlas.en-us.c360a_api.meta/c360a_api/c360a_api_sitemap.htm) documentation.

## Create a Website Data Stream

Now that you’ve set up your website connector and installed and initialized the SDK on your website, create a new data stream for your website connector.

1. In Data Cloud, navigate to the Data Streams tab and click **New**.
2. Under Connected Sources, click **Website** and then click **Next**.
3. From the Website dropdown, select the website connector you configured.
4. Select the events that you’d like to capture from your website and click **Next**.

   **note:** A single data stream with the category `Engagement` consolidates all engagement events, while each profile event is individually categorized into its own data stream with the category `Profile`.

5. Review and verify the events you selected and their associated fields.
6. Click **Next**.
7. If you have more than one data space, select the data space you’d like to use with this data stream from the Data Space dropdown.
8. For every profile event you’re capturing, use the Refresh Mode dropdown to select the data refresh mode as either **Incremental** or **Partial**.
9. Click **Deploy**.

## Map Website Connector Object Fields

Data ingested by all data streams is written to data lake objects (DLOs). After creating your data streams, associate your DLOs to data model objects (DMOs).

To start data mapping, access the Data Stream detail page for your newly created data stream and click Start Data Mapping. Doing so takes you to the field mapping canvas that displays your DLOs and target DMOs. To map one to another, click the name of a DLO and connect it to the desired DMO.

For your website data stream, map behavioral events and data as described in these sections.

- [Behavioral Events Data Mapping](#behavioral-events-data-mapping)

  - : Map fields in your website connector’s behavioral events DLO to the DMO.

- [Contact Point Address Data Mapping](#contact-point-address-data-mapping)

  - : Make sure that no fields are mapped in your website connector’s contact point address DLO to the DMO.

- [Contact Point Email Data Mapping](#contact-point-email-data-mapping)

  - : Map fields in your website connector’s contact point email DLO to the DMO.

- [Contact Point Phone Data Mapping](#contact-point-phone-data-mapping)

  - : Map fields in your website connector’s contact point phone DLO to the DMO.

- [Identity Data Mapping](#identity-data-mapping)

  - : Map fields in your website connector’s identity DLO to the DMO.

- [Party Identification Data Mapping](#party-identification-data-mapping)

  - : Map fields in your website connector’s party identification DLO to the DMO.

### Behavioral Events Data Mapping

Map fields in your website connector’s behavioral events DLO to the DMO. Behavioral event data is divided into several subsections in the mapping canvas.

| Section        | DLO Field                  | Map to DMO                       | DMO Field                                  |
| -------------- | -------------------------- | -------------------------------- | ------------------------------------------ |
| All Event Data | `dateTime`                 | Product Browse Engagement        | Created Date                               |
|                |                            | Product Browse Engagement        | Engagement Date Time                       |
|                |                            | Shopping Cart Engagement         | Created Date                               |
|                |                            | Shopping Cart Engagement         | Engagement Date Time                       |
|                |                            | Shopping Cart Product Engagement | Created Date                               |
|                |                            | Product Order Engagement         | Created Date                               |
|                |                            | Product Order Engagement         | Engagement Date Time                       |
|                | `deviceId`                 | Product Browse Engagement        | Individual                                 |
|                |                            | Shopping Cart Engagement         | Individual                                 |
|                |                            | Shopping Cart Product Engagement | Individual                                 |
|                |                            | Product Order Engagement         | Individual                                 |
|                | `eventId` (primary key)    | Product Browse Engagement        | Product Browse Engagement ID (primary key) |
|                |                            | Shopping Cart Engagement         | Shopping Cart Engagement ID (primary key)  |
|                |                            | Shopping Cart Product Engagement | Shopping Cart Engagement ID (primary key)  |
|                |                            | Product Order Engagement         | Product Order Engagement ID (primary key)  |
| Cart           | `eventType`                | Shopping Cart Engagement         | Engagement Type                            |
|                | `interactionName`          | Shopping Cart Engagement         | Engagement Channel Action                  |
| Cart Item      | `catalogObjectId`          | Shopping Cart Product Engagement | Product                                    |
|                | `catalogObjectType`        | Shopping Cart Product Engagement | Product Category                           |
|                | `currency`                 | Shopping Cart Product Engagement | Currency                                   |
|                | `price`                    | Shopping Cart Product Engagement | Product Price                              |
|                | `quantity`                 | Shopping Cart Product Engagement | Product Quantity                           |
|                | `eventType`                | Shopping Cart Product Engagement | Engagement Type                            |
| Catalog        | `id`                       | Product Browse Engagement        | Product                                    |
|                | `interactionName`          | Product Browse Engagement        | Engagement Channel Action                  |
|                | `productSku`               | Product Browse Engagement        | Product SKU                                |
|                | `personalizationId`        | Product Browse Engagement        | Personalization                            |
|                | `personalizationContentId` | Product Browse Engagement        | Personalization Content                    |
|                | `eventType`                | Product Browse Engagement        | Engagement Type                            |
| Order          | `eventType`                | Product Order Engagement         | Engagement Type                            |
|                | `interactionName`          | Product Order Engagement         | Engagement Channel Action                  |
|                | `orderId`                  | Product Order Engagement         | Correlation ID                             |
|                | `orderTotalValue`          | Product Order Engagement         | Adjusted Total Product Amount              |
|                | `orderTotalValue`          | Product Order Engagement         | Total Product Amount                       |
| Consent Log    | Not mapped                 | Not mapped                       | Not mapped                                 |
| Order Item     | Not mapped                 | Not mapped                       | Not mapped                                 |

### Contact Point Address Data Mapping

Don't map fields in your website connector’s contact point address DLO to the DMO.

| contactPointAddress DLO Field | Contact Point Address DMO Field |
| ----------------------------- | ------------------------------- |
| Not mapped                    |                                 |

### Contact Point Email Data Mapping

Map these fields in your website connector’s contact point email DLO to the DMO.

| contactPointEmail DLO Field | Contact Point Email DMO Field                                        |
| --------------------------- | -------------------------------------------------------------------- |
| `dateTime`                  | Created Date                                                         |
| `deviceId` (primary key)    | <ul><li>Contact Point Email ID (primary key)</li><li>Party</li></ul> |
| `email`                     | Email Address                                                        |

### Contact Point Phone Data Mapping

Map these fields in your website connector’s contact point phone DLO to the DMO.

| contactPointPhone DLO    | Contact Point Phone DMO Field                                        |
| ------------------------ | -------------------------------------------------------------------- |
| `dateTime`               | Created Date                                                         |
| `deviceId` (primary key) | <ul><li>Contact Point Phone ID (primary key)</li><li>Party</li></ul> |
| `phoneNumber`            | Telephone Number                                                     |

### Identity Data Mapping

Map these fields in your website connector’s identity DLO to the DMO.

| identity DLO Field       | Individual DMO Field        |
| ------------------------ | --------------------------- |
| `dateTime`               | Created Date                |
| `deviceId` (primary key) | Individual ID (primary key) |
| `firstName`              | First Name                  |
| `isAnonymous`            | Is Anonymous                |
| `lastName`               | Last Name                   |
| `userName`               | External Record ID          |

### Party Identification Data Mapping

Map these fields in your website connector’s party identification DLO to the DMO.

| partyIdentification DLO Field | Party Identification DMO Field                                          |
| ----------------------------- | ----------------------------------------------------------------------- |
| `dateTime`                    | Created Date                                                            |
| `deviceId` (primary key)      | <ul><li>Party</li><li> Party Identification ID (primary key) </li></ul> |
| `IDName`                      | Identification Name                                                     |
| `IDType`                      | Party Identification Type                                               |
| `userId`                      | Identification Number                                                   |

For more information about data mapping in Data Cloud, see [Data Mapping](https://help.salesforce.com/s/articleView?id=sf.c360_a_data_mapping.htm).

<!-- document id=d6ff24de8f9fe596a2fb3a5bccd31e6dd504012e973f46b0bff59e6e0d93224f url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/mobile-integration/configure-mobile-personalization/personalize-mobile-experiences-ios.md -->

# iOS Integration

Configure the iOS app to identify users and manage consent settings, enabling you to request and display content tailored to specific user interactions.

1. [Install the SDK](#install-the-sdk)
2. [Initialize the Data 360 and Personalization Modules](#initialize-the-data-360-and-personalization-modules)
3. [Request Personalization](#request-personalization)
4. [Access Responses](#access-responses)
5. [Example with Request and Response](#example-with-request-and-response)
6. [Error Handling](#error-handling)

## Install the SDK

Add the Personalization module to your Xcode project using Swift Package Manager or CocoaPods.

1. Install the Personalization module using either the Swift Package Manager (SPM) or Cocoapods. The Data 360 (CDP) module is pulled in automatically as a transitive dependency - you don't install it separately.

   - **Swift Package Manager** In Xcode, add this repository to your Xcode project.
     `https://github.com/salesforce-marketingcloud/Personalization-IOS`

   - **Cocoapods** Include this pod in your Podfile. See [Personalization-IOS](https://cocoapods.org/pods/Salesforce-Personalization).
     `pod 'Salesforce-Personalization'`

2. Integrate Data 360 (CDP) behavior tracking, consent, and identity for your app. See [Install the SDK](https://developer.salesforce.com/docs/data/data-cloud-engagement-mobile-sdk/guide/c360a-api-engagement-mobile-sdk.html#install-the-sdk).

## Initialize the Data 360 and Personalization Modules

The host app owns SDK initialization. Initialize both the [Data 360 module](https://developer.salesforce.com/docs/data/data-cloud-engagement-mobile-sdk/guide/c360a-api-engagement-mobile-sdk-initialization.html) and the Personalization module in your app delegate's `application(_:didFinishLaunchingWithOptions:)`, before making any `fetchDecisions` calls.

```swift
import SFMCSDK
import Cdp
import Personalization

/* Initialization of the CDP module for data collection */
let flushRate = EventFlushRate.Quantity(quantity = 1)

let cdpConfig = CdpConfigBuilder(
    appId: "<Your Data 360 Connector appId>",
    endpoint: "<Your Data 360 Connector endpoint>")
    .eventFlushRate(flushRate)
    .build()

/* Create an instance of a personalization module configuration */
let personalizationConfig = PersonalizationConfigBuilder()
    // Optionally define your dataspace. The "default" data space is used if you don't explicitly provide one.
    .dataspace("myDataspaceApiName")
    .build()

/* Combine both CDP and Personalization configurations using ConfigBuilder, then initialize the SDK */
let sdkConfig = ConfigBuilder()
    .setCdp(config: cdpConfig)
    .setPersonalization(config: personalizationConfig)
    .build()

SFMCSdk.initializeSdk(sdkConfig) { statuses in
    // Handle module initialization statuses
    statuses.forEach { status in
        SFMCSdkLogger.shared.logMessage(
            level: .debug,
            subsystem: .module(value: status.moduleName),
            category: .module,
            message: "Module \(status.moduleName.rawValue) result \(status.initStatus.rawValue)"
        )
    }
}
```

**note:** In your production application, you must explicitly manage user consent using the solution provided in the Engagement Mobile SDK. See [Data 360 Consent Management](https://developer.salesforce.com/docs/data/data-cloud-engagement-mobile-sdk/guide/c360a-api-engagement-mobile-sdk-consent-management.html).

### Considerations

- Call this initialization once, from `application(_:didFinishLaunchingWithOptions:)` - not from a view controller - so the SDK is ready before any screen requests decisions.
- The system uses the `default` data space if you don't explicitly provide one.
- To enable debug logging during development, add this snippet before `SFMCSdk.initializeSdk(...)`, so logging is active for the whole init sequence. Make sure this setting is disabled or removed before building your application for production.

  ```swift
  SFMCSdk.setLogger(logLevel: .debug)
  ```

  For more information on logging, see [Logging and Debugging](https://developer.salesforce.com/docs/data/data-cloud-engagement-mobile-sdk/guide/c360a-api-engagement-mobile-sdk-logging-and-debugging.html).

## Request Personalization

To retrieve personalization decisions, call `fetchDecisions()` with the personalization point API Names.

```swift
import Personalization

let response = try await PersonalizationModule.fetchDecisions(
    personalizationPointNames: ["homeHero", "productRecommendations"]
)
```

The `fetchDecisions` method enables you to interact with the Decisioning API and request one or more personalizations for specific areas of your mobile application.

### Method Signature

Use the `fetchDecisions` method structure to define how your app requests and receives personalization decisions.

```swift
@objc public static func fetchDecisions(
    personalizationPointNames: [String],
    decisionsRequestContext: DecisionsRequestContext? = nil,
    timeoutSeconds: TimeInterval = 10) async throws -> DecisionsResponse
```

| Parameter                 | Description                                                                                                                                                                    |
| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| personalizationPointNames | List of at least one personalization point API Name (not the display label) for which you want to return decisions.                                                            |
| context                   | (Optional) Additional context information. If you don't have any context, pass nil. See [Request Personalization By Using Context](#request-personalization-by-using-context). |
| timeoutSeconds            | (Optional) The duration, in seconds, before the fetch task times out. The default is 10 seconds.                                                                               |

If successful, this request returns a `DecisionsResponse` object. If the task is canceled, it throws a `PersonalizationError`, or a `CancellationError` error.

### Request Personalization By Using Context

You can use additional context to influence personalization decisions. Use this method only if you have specific context available to affect the decisions. To know about context variables and how they can be used, see [Filter Recommendations Using Dynamic Context Variables](https://help.salesforce.com/s/articleView?id=mktg.persnl_recommender_filter_using_dynamic_variable.htm).

```swift
/* Optionally use a request context */
let decisionsRequestContext = DecisionsRequestContextBuilder()
    // Optionally define the anchor item for your recommendations
    .anchorId("PRODUCT_123")

    // Optionally define type of an anchor item
    .anchorDmoName("ssot__GoodsProduct__dlm")

    // Optionally define the contextual attributes and their values
    .contextualAttribute(name: "category", value: "shoes")
    .contextualAttribute(name: "color", value: "red")

    .build()

let response = try await PersonalizationModule.fetchDecisions(
    personalizationPointNames: [pointName],
    context: decisionsRequestContext
)
```

For the `DecisionsRequestContext` builder, you can optionally add these fields.

| Optional Field        | Description                                                                                                                                                                                                                                                                                                                                                                                                                         |
| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `anchorID`            | The unique identifier of the specific item the user is currently viewing. This is helpful in context-aware strategies, such as "People who bought this item also bought…"                                                                                                                                                                                                                                                           |
| `anchorDmoName`       | The API Name of the DMO or the name of the item type (for example, Product or Article) that corresponds to the anchorId. This tells the system what kind of item the anchor is. The DMO name should correspond to the actual one set up in Data 360. Example: `ssot__GoodsProduct__dlm`. If omitted, the system infers the anchor type from `anchorId` automatically.                                                               |
| `contextualAttribute` | Run-time attributes that help refine recommendation responses and enable advanced filtering logic in your recommenders. To pass multiple attributes, chain a separate method call for each specific key-value pair. For information on contextual attributes, see [Filter Recommendations Using Dynamic Context Variables](https://help.salesforce.com/s/articleView?id=mktg.persnl_recommender_filter_using_dynamic_variable.htm). |

The `fetchDecisions` method interacts with the Decisioning API and requests one or more personalizations for specific areas of your mobile application.

```swift
let response = try await PersonalizationModule.fetchDecisions(
    personalizationPointNames: ["Hero_Banner", "Footer_Promo"],
    context: decisionsRequestContext
    // Applies to ALL personalization points above
)
```

## Access Responses

The `fetchDecisions` method returns a `DecisionsResponse` object. This object contains both the raw list of personalizations and an optimized dictionary lookup.

### `DecisionsResponse` Structure

| Field                  | Type                                         | Description                                                                                                       |
| :--------------------- | :------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
| requestId              | String                                       | The identifier associated with the underlying network request, useful for diagnostics.                            |
| personalizations       | \[DecisionsResponsePersonalization\]         | A list of all personalization objects returned.                                                                   |
| personalizationsByName | \[String: DecisionsResponsePersonalization\] | A dictionary of personalization points indexed by name. We recommend this instead of a list for efficient access. |

### `DecisionsResponsePersonalization` Structure

Each item in the `personalizations` list (accessible via `personalizationsByName`) represents the content returned for a specific personalization point:

| Field                    | Type                               | Description                                                                                                                                        |
| :----------------------- | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| personalizationPointName | String                             | The name of the personalization point requested.                                                                                                   |
| attributes               | \[String: Any\]                    | The dictionary of attributes (metadata) returned for this personalization. The schema is defined by the personalization setup.                     |
| data                     | \[DecisionsResponseContentObject\] | A list of content items (the actual personalized content).                                                                                         |
| decisionId               | String?                            | The optional identifier for the specific decision made by the server.                                                                              |
| `personalizationId`      | String                             | The unique identifier for specific personalization result. This identifier can be used for tracking, analytics, or correlation with other systems. |

### Example to Access Response Content

```swift
let response = try await PersonalizationModule.fetchDecisions(
    personalizationPointNames: ["homeHero", "productRecs"]
)

// Using dictionary lookup (preferred) for a specific personalization point
if let homeHero = response.personalizationsByName["homeHero"] {
    // Access personalization attributes
    if let title = homeHero.attributes["title"] as? String {
        print("Title: \(title)")
    }

    // Access recommended items
    for item in homeHero.data {
        print("Content ID: \(item.personalizationContentId)")
        // Access item properties...
    }
}

// Or iterate through all personalizations
for personalization in response.personalizations {
    print("Point: \(personalization.personalizationPointName)")
    print("Items: \(personalization.data.count)")
}
```

In the example, `fetchDecisions` sends the user context to the server to request content for both `homeHero` and `product_recs` simultaneously. Once the response arrives, `personalizationsByName` allows you to access the results for each point independently.

## Example with Request and Response

```swift
import Personalization

// DecisionsRequestContext is optional. We recommend including it only when necessary.
let decisionsRequestContext = DecisionsRequestContextBuilder()
    // Optionally define the anchor item for your recommendations.
    .anchorId("PRODUCT_123")

    // Optionally define the API name of the DMO of the anchor item.
    .anchorDmoName("ssot__GoodsProduct__dlm")

    // Optionally define the contextual attributes and their values.
    .contextualAttribute(name: "category", value: "shoes")
    .contextualAttribute(name: "color", value: "red")

    .build()

// This example ignores error details. To capture error information, see the Error Handling section.
guard let response = try? await PersonalizationModule.fetchDecisions(
    // Supports multiple points, as desired.
    personalizationPointNames: ["Product_Recs", "Footer_Promo"],
    // Applies to ALL personalization points above.
    decisionsRequestContext: decisionsRequestContext
) else {
    return
}

if let productRecs = response.personalizationsByName["Product_Recs"] {
    // Retrieve and validate the IntroductionText attribute from the response template. We recommend setting a fallback value.
    guard let rawValue = productRecs.attributes["IntroductionText"] as? String, !rawValue.isEmpty else {
        // Or use your custom logger.
        print("Product_Recs personalization: IntroductionText: Not found, not string, or empty, using fallback value.")
        return
    }
    let introText = rawValue
    // Use introText for your requirements (this example just prints).
    print("Product_Recs personalization: IntroductionText: \(introText)")
    // ... repeat for other attributes.

    // Loop through your recommended items.
    productRecs.data.enumerated().forEach { (index, contentObject) in
        // This example shows no fallback value.
        if let itemName = contentObject["Name"] as? String, !itemName.isEmpty {
            // Use itemName for your requirements (this example just prints).
            print("Product_Recs data[\(index)]: itemName: \(itemName)")
        } else {
            // Or use your custom logger.
            print("Product_Recs data[\(index)]: itemName: Not found, not string, or empty.")
        }
        // ...similarly repeat for other contentObject properties.
    }

} else {
    // Or use your custom logger.
    print("No personalization for point Product_Recs")
    return
}

if let footerPromo = response.personalizationsByName["Footer_Promo"] {
    // ...Obtain and validate expected attributes as demonstrated above.
} else {
    // Or use your custom logger.
    print("No personalization for point Footer_Promo")
    return
}
```

## Error Handling

Implement error handling for decision fetching. We recommend logging the exception.

### Swift

```swift
// Simple Error Handling (Recommended)

guard let response = try? await PersonalizationModule.fetchDecisions(
    personalizationPointNames: ["homeHero"]
) else {
    return // Handle failure
}
// Use response...

// Detailed Error Handling (Optional)

do {
    let response = try await PersonalizationModule.fetchDecisions(
        personalizationPointNames: ["homeHero"]
    )
    // Use response...
} catch PersonalizationError.initialization(let reason) {
    print("Initialization error: \(reason)")
} catch PersonalizationError.consent(let reason) {
    print("Consent error: \(reason)")
} catch PersonalizationError.timeout(let reason) {
    print("Timeout error: \(reason)")
} catch PersonalizationError.responseInvalid(let reason) {
    print("Response invalid: \(reason)")
} catch is CancellationError {
    print("Task was cancelled")
} catch {
    print("Other error: \(error)")
}
```

### Objective-C

```
NSError *error = nil;
SFPDecisionsResponse *response = [SFPersonalizationModule
    fetchDecisionsWithPersonalizationPointNames:@[@"homeHero"]
    context:nil
    timeoutSeconds:10.0
    error:&error];
if (error) {
    // Check error.domain and error.code
    // See PersonalizationErrorInfo.domain and PersonalizationErrorCode
    NSLog(@"Error: %@", error);
} else {
    // Use response...
}
```

<!-- document id=87dac7d7a2a62e8d38a0944bf1f09e914d9c164f28611f20fcffefe989b0715f url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/mobile-integration/configure-mobile-personalization/personalize-mobile-experiences-lowcode-ios.md -->

# iOS Low-Code Integration

Use the LowCodeMobile iOS SDK to display personalized content in your iOS app with minimal setup. The SDK renders out-of-the-box Banner and Recommendations components and supports custom components for fully custom UI.

1. [Install the SDK](#install-the-sdk)
2. [Initialize the SDK](#initialize-the-sdk)
3. [Display a Content Zone](#display-a-content-zone)
4. [Out-of-the-Box Components](#out-of-the-box-components)
5. [Custom Components](#custom-components)
6. [Engagement Tracking](#engagement-tracking)
7. [Preview](#preview)
8. [Design-Time Rendering](#design-time-rendering)
9. [Error Handling](#error-handling)

## Install the SDK

### Swift Package Manager

In Xcode, add the LowCodeMobile package to your project. The Personalization, Data 360, and Salesforce Marketing Cloud SDK packages are pulled in transitively. Xcode limits updates to within the same major version by default when you specify the package.

```
https://github.com/salesforce-marketingcloud/LowCode-IOS
```

Selecting your app target when adding the package should automatically add the `LowCodeMobile` framework to it, but it's worth confirming under General > Frameworks, Libraries, and Embedded Content.

### CocoaPods

Add the pods to your app's Podfile. The Personalization, Data 360, and Salesforce Marketing Cloud SDK packages are pulled in transitively. Limit updates to within the same major version to avoid unexpected breaking changes:

```
pod 'Salesforce-LowCodeMobile', '~> 1.2'
```

Then run:

```shell
pod install
```

Open the `.xcworkspace` file, then clean and build.

### Required SDK Levels

Your app's SDK levels must meet or exceed the following minimums.

| Setting               | Required |
| :-------------------- | :------- |
| iOS deployment target | 15.0+    |
| Xcode                 | 26.2+    |
| Swift                 | 5.9+     |

## Initialize the SDK

The host app owns SDK initialization. Initialize both the Data 360 (CDP) and Personalization modules early in your application lifecycle: in SwiftUI, call this from your `App` type's `init()`; in UIKit, call it from `AppDelegate.application(_:didFinishLaunchingWithOptions:)`. The SDK queues any content zone requests made before initialization completes, so you do not need to gate your UI on init status.

```swift
import SFMCSDK
import Cdp
import Personalization

// Send every event to Data 360 in Real Time
let flushRate = EventFlushRateQuantity(quantity: 1)

let cdpConfig = CdpConfigBuilder(
    appId: "<Your Data 360 App ID>",
    endpoint: "<Your Tenant Specific Endpoint>")
    .eventFlushRate(flushRate)
    .build()

let personalizationConfig = PersonalizationConfigBuilder()
    .dataspace("default") // Replace with your dataspace if not using default
    .cdnUrl("<Your CDN URL>")
    .build()

let sdkConfig = ConfigBuilder()
    .setCdp(config: cdpConfig)
    .setPersonalization(config: personalizationConfig)
    .build()

SFMCSdk.initializeSdk(sdkConfig) { statuses in
    statuses.forEach { status in
        print("Module \(status.moduleName.rawValue) initialized: \(status.initStatus.rawValue)")
    }
}
```

**note:** In your production application, you must explicitly manage user consent using the solution provided in the Engagement Mobile SDK. See [Data 360 Consent Management](https://developer.salesforce.com/docs/data/data-cloud-engagement-mobile-sdk/guide/c360a-api-engagement-mobile-sdk-consent-management.html).

### Considerations

- Replace `<Your CDP App ID>`, `<Your CDP Endpoint>`, and `<Your CDN URL>` with the values provided by your Salesforce Marketing Cloud administrator.
- To avoid committing credentials, read these values from `Info.plist` or a build configuration file.
- To enable debug logging during development, add `SFMCSdk.setLogger(logLevel: .debug)` before `SFMCSdk.initializeSdk(...)`, so logging is active for the whole init sequence. Remove this before building for production.

## Display a Content Zone

Once the SDK is initialized, use `ContentZone` in your SwiftUI views to display personalized content.

Pass the content zone identifier and a list of components the zone is allowed to render. The SDK fetches a decision from the backend, matches the component name returned, and renders the matching component.

After adding a ContentZone to your app code, create the matching content zone record in Salesforce Personalization. See [Set Up Mobile Content Zones](https://help.salesforce.com/s/articleView?id=mktg.persnl_experience_mobile_content_zones_register.htm) for instructions on defining personalization points, assigning components, and configuring engagement definitions.

### SwiftUI

```swift
import LowCodeMobile

struct HomeView: View {
    var body: some View {
        ContentZone(
            name: "HomeScreen",
            allowedComponents: [
                SalesforceBanner(),
                SalesforceRecommendations()
            ]
        )
    }
}
```

`ContentZone` is a standard SwiftUI view - place it anywhere in your layout alongside other content. The [Pull-to-refresh](#pull-to-refresh) example below shows it embedded within a scrollable screen.

### ContentZone Parameters

| Parameter                 | Required | Description                                                                                                  |
| :------------------------ | :------- | :----------------------------------------------------------------------------------------------------------- |
| `name`                    | Yes      | The content zone identifier, matching your backend configuration (case-sensitive).                           |
| `allowedComponents`       | Yes      | The `Components` the zone may render. If the backend returns a name not in this list, the fallback is shown. |
| `decisionsRequestContext` | No       | Optional context to bias personalization decisions.                                                          |
| `timeoutSeconds`          | No       | Fetch timeout in seconds. Default: 10.                                                                       |
| `controller`              | No       | `ContentZoneController` for programmatic refresh.                                                            |
| `loading`                 | No       | View shown while content is loading.                                                                         |
| `fallback`                | No       | View shown when content cannot be loaded or no component matches.                                            |

### Pull-to-refresh

Use a `ContentZoneController` to refresh the zone programmatically:

```swift
struct HomeScreen: View {
    @StateObject var zoneController = ContentZoneController()

    var body: some View {
        ScrollView {
            Text("Welcome back!") // Other content in your screen

            ContentZone(
                name: "HomeScreen",
                controller: zoneController,
                allowedComponents: [SalesforceBanner(), SalesforceRecommendations()]
            )

            // Additional content below the zone
        }
        .refreshable {
            await zoneController.refresh()
        }
    }
}
```

## Out-of-the-Box Components

The SDK ships with two pre-built components - `SalesforceBanner` and `SalesforceRecommendations` - that handle layout, styling, and configuration-driven engagement tracking out of the box. Use these when you want to display personalized content without writing a custom UI. Both support an `onTap` callback for custom tap handling; by default, tapping opens the `ctaUrl` if one is provided by the backend.

These components are available out-of-the-box in the UI and are registered under the names `"Salesforce_Banner"` and `"Salesforce_Recommendations"`.

### SalesforceBanner

```swift
ContentZone(
    name: "HomeScreen",
    allowedComponents: [
        SalesforceBanner(
            onTap: { model in
                // Custom tap handling - default behavior opens ctaUrl if provided
                print("Banner tapped: \(model.header)")
            }
        )
    ],
    loading: { ProgressView() },
    fallback: { _ in Text("Content unavailable") }
)
```

### SalesforceRecommendations

Pass a `DecisionsRequestContext` to bias recommendations based on what the user is currently viewing. All fields are optional - if you only supply `anchorId`, the system infers the type automatically.

```swift
let context = DecisionsRequestContextBuilder()
    .anchorId("PRODUCT_123")
    // Optional: explicitly specify the anchor type. If omitted, the system infers it from anchorId.
    .anchorDmoName("ssot__GoodsProduct__dlm")
    .contextualAttribute(name: "category", value: "shoes")
    .build()

ContentZone(
    name: "ProductRecommendations",
    allowedComponents: [
        SalesforceRecommendations(
            onTap: { event in
                // Custom tap handling - default behavior opens ctaUrl if provided
                print("Tapped item: \(event.item.name) at index \(event.index)")
            }
        )
    ],
    decisionsRequestContext: context
)
```

### Custom Styling Example for `SalesforceBanner`

Override the default appearance of out-of-the-box components by passing a style object:

```swift
import LowCodeMobile

ContentZone(
    name: "HomeScreen",
    allowedComponents: [
        SalesforceBanner(
            style: BannerStyle(
                backgroundColor: Color(red: 0.96, green: 0.96, blue: 0.96),
                headerTextColor: Color(red: 0.1, green: 0.1, blue: 0.1),
                contentPadding: 16
            )
        )
    ]
)
```

## Custom Components

Implement the `Component` protocol to render a content zone with your own UI. Each component defines:

- `static var name`: String - The component name that matches the backend experience template name.
- `validateAndCreateComponentModel`(unvalidatedJson:componentContext:) - Decodes and validates the JSON payload and returns a typed model, or throws a PersonalizationError
- `compose`(model:componentContext:) - Returns the SwiftUI view for the component.

### Define a custom component

Define a custom component with its own component name, model, and associated experience template in the backend. Give the component a unique name (for example, `CustomHero`), then create a matching experience template in the Core UI and a matching custom component in your app. Your model's fields and types must match the experience template's schema, though you don't need to use all of them.

```swift
import SwiftUI
import LowCodeMobile
import Personalization

struct HeroModel: ComponentModel {
    let header: String
    let imageUrl: String
    let ctaText: String?
}

struct HeroView: View {
    let model: HeroModel
    let componentContext: ComponentContext

    var body: some View {
        VStack(alignment: .leading) {
            AsyncImage(url: URL(string: model.imageUrl)) { image in
                image.resizable().aspectRatio(contentMode: .fill)
            } placeholder: {
                Color.gray.opacity(0.2)
            }
            .frame(height: 200)
            .clipped()
            Text(model.header)
                .font(.headline)
                .frame(maxWidth: .infinity, alignment: .center)
            if let cta = model.ctaText {
                Text(cta)
                    .font(.subheadline)
                    .frame(maxWidth: .infinity, alignment: .center)
                    .foregroundColor(.blue)
            }
        }
        .onTapGesture {
            // Track clicks when the user taps
            componentContext.trackEngagement(action: EngagementAction.click)
            // You could add a tapUrl to the model and open/route as well
        }
        // Track a view once per personalization
        .sfpTrackEngagementViewOnce(componentContext)
    }
}

class CustomHero: Component {
    public static let name = "CustomHero"
    public typealias Content = HeroView
    public typealias Model = HeroModel

    func validateAndCreateComponentModel(unvalidatedJson: Data, componentContext: ComponentContext) throws -> HeroModel {
        let model = try JSONDecoder().decode(HeroModel.self, from: unvalidatedJson)
        // Optional validations here, e.g. throw when a required field is blank:
        // guard !model.header.isEmpty else {
        //     throw PersonalizationError.responseInvalid("header cannot be blank")
        // }
        return model
    }

    func compose(model: HeroModel, componentContext: ComponentContext) -> Content {
        return HeroView(model: model, componentContext: componentContext)
    }
}

// Usage
ContentZone(
    name: "HomeScreen",
    allowedComponents: [CustomHero()]
)
```

### Define a multi-item custom component

For a component that renders a list (like `SalesforceRecommendations`), use the per-item variants of the engagement functions to report engagement for each item in the list.

```swift
import SwiftUI
import LowCodeMobile
import Personalization

struct ItemListModel: ComponentModel {
    let sectionHeader: String?
    let items: [ItemModel]
}

struct ItemModel: Decodable {
    let id: String
    let title: String
    let imageUrl: String
    let description: String
}

struct ItemListView: View {
    let model: ItemListModel
    let componentContext: ComponentContext

    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            // Optional header above all the items
            if let sectionHeader = model.sectionHeader {
                Text(sectionHeader)
                    .font(.headline)
                    .frame(maxWidth: .infinity, alignment: .center)
            }
            // Each item
            ForEach(Array(model.items.enumerated()), id: \.element.id) { index, item in
                ItemView(index: index, model: item, componentContext: componentContext)
            }
        }
    }
}

struct ItemView: View {
    let index: Int
    let model: ItemModel
    let componentContext: ComponentContext

    var body: some View {
        HStack(alignment: .center) {
            // Image on the left
            AsyncImage(url: URL(string: model.imageUrl)) { image in
                image
                    .resizable()
                    .aspectRatio(contentMode: .fill)
                    .clipped()
            } placeholder: {
                Color.gray.opacity(0.2)
            }
            .frame(width: 100, height: 100)
            .clipped()
            // Text on the right
            VStack(alignment: .leading, spacing: 8) {
                Text(model.title)
                    .font(.headline)
                    .lineLimit(1)
                    .truncationMode(.tail)
                Text(model.description)
                    .font(.subheadline)
                    .lineLimit(1)
                    .truncationMode(.tail)
            }
            .frame(maxWidth: .infinity, alignment: .leading)
        }
        .frame(minHeight: 100)
        .onTapGesture {
            // Track clicks when the user taps
            componentContext.trackEngagementPerItem(index: index, action: EngagementAction.click)
            // You could add a tapUrl to the model and open/route as well
        }
        // Track a view once per personalization, per item
        .sfpTrackEngagementViewOncePerItem(componentContext, index: index)
    }
}

/// Expected to be used in a ContentZone within a scrollable area, ie has a parent ScrollView
class CustomItemList: Component {
    public static let name = "CustomItemList"
    public typealias Content = ItemListView
    public typealias Model = ItemListModel

    func validateAndCreateComponentModel(unvalidatedJson: Data, componentContext: ComponentContext) throws -> ItemListModel {
        let model = try JSONDecoder().decode(ItemListModel.self, from: unvalidatedJson)
        // Optional validations here, e.g. throw if an item is missing a required field
        // throw PersonalizationError.responseInvalid("...")
        return model
    }

    func compose(model: ItemListModel, componentContext: ComponentContext) -> Content {
        return ItemListView(model: model, componentContext: componentContext)
    }
}

// Usage
ContentZone(
    name: "HomeScreen",
    allowedComponents: [CustomItemList()]
)
```

## Engagement Tracking

Out-of-the-box components (`SalesforceBanner`, `SalesforceRecommendations`) track `View` and `Click` engagement automatically. These are the only two actions currently supported end-to-end. The SDK accepts custom action strings for future expansion.

For custom components, engagement is not automatic - you must call these methods explicitly from your component code:

| Function                                                       | Use for                                                                                                     |
| :------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
| `componentContext.trackEngagement(action:)`                    | Clicks on a single-item component (e.g. `CustomHero`)                                                       |
| `componentContext.trackEngagementPerItem(index:action:)`       | Clicks on an item within a multi-item component (e.g. `CustomItemList`)                                     |
| `.sfpTrackEngagementViewOnce(componentContext)`                | Views of a single-item component - a View modifier, applied once per personalization                        |
| `.sfpTrackEngagementViewOncePerItem(componentContext, index:)` | Views of an item within a multi-item component - a View modifier, applied once per item per personalization |

See [Define a custom component](#define-a-custom-component) and [Define a multi-item custom component](#define-a-multi-item-custom-component) above for both in use.

## Preview

The SDK supports previewing personalized content via QR code or preview URL. When a URL containing the `sfp-preview` parameter is opened, the SDK renders preview content in all active content zones.

Before using preview, ensure:

1. Your app is configured to handle URL schemes or Universal Links (via Associated Domains and your app's entitlements).
2. The base URL is set in your Data 360 mobile connector configuration.

### SwiftUI

```swift
@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView() // Your app's root View
                .onOpenURL { url in
                    PersonalizationModule.handlePreviewURL(url)
                }
        }
    }
}
```

### UIKit

The appropriate URL-handling method depends on your app's lifecycle and the iOS versions you support (e.g. `application(_:open:options:)`, `scene(_:openURLContexts:)` for SceneDelegate, or Universal Links via `application(_:continue:restorationHandler:)`). The example below uses the AppDelegate method:

```swift
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    PersonalizationModule.handlePreviewURL(url)
    return true
}
```

## Design-Time Rendering

Use `MockDataContentZone` to render components with mock data for styling and layout without any backend setup or networking. This is not related to QR-code based previewing - it simply lets you see how components look during development.

```swift
#Preview { // SwiftUI design-time rendering - not related to QR-code based previewing
    MockDataContentZone(
        name: "HomeScreen",
        allowedComponents: [SalesforceBanner(), SalesforceRecommendations()],
        mockContent: {
            BannerModel(
                header: "Summer Sale",
                imageUrl: "https://example.com/banner.png",
                ctaText: "Shop Now",
                ctaUrl: "https://example.com/sale"
            )
        }
    )
}
```

To try out your `fallback` view, throw an error from the closure:

```swift
#Preview("Error State") {
    MockDataContentZone(
        name: "HomeScreen",
        allowedComponents: [SalesforceBanner()],
        mockContent: { throw PersonalizationError.timeout("Preview timeout") }
    )
}
```

## Error Handling

The SDK uses the `PersonalizationError` enum for error reporting:

| Error Case         | Description                                               |
| :----------------- | :-------------------------------------------------------- |
| `.unknown`         | An unknown error occurred.                                |
| `.initialization`  | The SDK has not been initialized or failed to initialize. |
| `.consent`         | User consent is not set to opt-in.                        |
| `.requestInvalid`  | The request parameters are invalid.                       |
| `.network`         | A network error occurred during the fetch.                |
| `.responseInvalid` | The server response could not be parsed.                  |
| `.timeout`         | The fetch request exceeded the timeout duration.          |

ContentZone handles errors internally. If no `fallback` is provided, the zone logs the error and shows nothing - this is the typical production behavior. If you want to display fallback content, pass a `fallback` view. The following example is for illustration only - consider what behavior is appropriate for your production app:

```swift
ContentZone(
    name: "HomeScreen",
    allowedComponents: [SalesforceBanner()],
    fallback: { error in
        if let persError = error as? PersonalizationError {
            switch persError {
            case .timeout:
                Text("Request timed out. Pull to refresh.")
            case .network:
                Text("No network connection.")
            default:
                Text("Content unavailable.")
            }
        }
    }
)
```

<!-- document id=30cfc7023333243c130168a060d0b1cb7d1bca509da22d8c5c583e43cb8ed722 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/mobile-integration/configure-mobile-personalization/personalize-mobile-experiences-lowcode.md -->

# Low-Code Mobile Personalization

Low-code mobile personalization uses pre-built SDK plugins that render personalized content for you. Instead of calling the Decisioning API directly and building your own UI, you use a `ContentZone` element in your app with a list of allowed components, and the SDK fetches content, matches the backend's component name, and renders the result automatically.

## How It Works

1. The host app initializes the native Personalization Module of the Unified SDK on startup.
2. You place a `ContentZone` in your UI and specify which components it may render.
3. The SDK fetches a personalization decision from the backend.
4. The matching component is rendered. If no match is found, an optional fallback is shown.

## When to use

Low-code integration is best for standard content zones and rapid integration, and custom components can also handle highly custom layouts. For a full comparison, see [Low-Code vs. Pro-Code](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences.md#low-code-vs-pro-code).

## Out-of-the-Box Components

The low-code SDKs ship two ready-to-use components on each platform (packaged differently per platform):

- **SalesforceBanner** - A single card with image, title, subtitle, and a CTA. Backed by the `Salesforce_Banner` template.
- **SalesforceRecommendations** - A scrollable list of recommendation cards. Backed by the `Salesforce_Recommendations` template.

Out-of-the-box components track `View` and `Click` engagement automatically.

## Custom Components

By implementing the `Component` interface, you can build your own UI component backed by an experience template with a distinct component name.

Whether you use an out-of-the-box (`Salesforce_Banner` or `Salesforce_Recommendations`) or fully custom experience template to create a custom component, you assign each custom component a new component name and handle these tasks in the app:

- Parse the decision JSON
- Render the UI
- Report `View` and `Click` engagement using the SDK's engagement tracking APIs

For implementation details, see the [platform guides](#platform-guides).

## Prerequisites

The low-code plugins depend on the same underlying native SDKs as the pro-code path. Before integrating a plugin:

- Complete the [Data 360 Engagement Mobile SDK](https://developer.salesforce.com/docs/data/data-cloud-engagement-mobile-sdk/guide/c360a-api-engagement-mobile-sdk.html) setup for identity, consent, and behavioral data collection.
- Configure a Mobile Connector in Data 360 and obtain your **CDP_APP_ID**, **CDP_ENDPOINT**, **CDN_URL**, and **DATASPACE** from your Data Cloud administrator.
- For the live previews functionality, configure a custom URL schema in your application.

## Platform Guides

- [iOS](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-lowcode-ios.md)
- [Android](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-lowcode-android.md)
- [React Native](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-lowcode-reactnative.md)
- [Flutter](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-lowcode-flutter.md)

## See Also

- [Configure Your Mobile App for Personalization](https://help.salesforce.com/s/articleView?id=mktg.persnl_experience_mobile_app_configure.htm)
- [Create a Mobile Experience Template](https://help.salesforce.com/s/articleView?id=mktg.persnl_experience_mobile_template_create.htm)

<!-- document id=14387f1c926d4df9821b22381e22e25b4afb250441f683208c1518aee111f766 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/personalization-content-view-attribution-dmo.md -->

# Personalization Content First Touch View-Based Attribution DMO

The Personalization Content First Touch View-Based Attribution Data Model Object (DMO) captures first-touch engagement data attributed to viewing personalized content. The data is aggregated by content.

## Object API Name

`PersnlContentFirstTouchViewAttr__dlm`

## Primary Key

Personalization Attribution Primary Key (`PersonalizationAttrPk__c`)

## All Fields

| Field Name                    | Field API Name                   | Description                                                                                                       | Data Type |
| ----------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------- |
| Internal Organization         | `InternalOrganization__c`        | Reference ID to the business unit or other internal organization that owns the business account.                  | text      |
| Data Source                   | `DataSource__c`                  | Reference ID for the logical name for a system that is the source of records identified by an external record ID. | text      |
| Data Source Object            | `DataSourceObject__c`            | Reference ID for the logical name of the object where this record came from.                                      | text      |
| Attribution Date              | `AttributionDate__c`             | Date of the first engagement that led to the attribution.                                                         | dateTime  |
| Data Space                    | `DataSpace__c`                   | The data space associated with this DMO                                                                           | text      |
| Personalization Point         | `PersonalizationPoint__c`        | Personalization point where data was gathered.                                                                    | text      |
| Personalization Decision      | `PersonalizationDecision__c`     | Personalization Decision assigned to the personalization point.                                                   | text      |
| Personalizer                  | `Personalizer__c`                | Personalizer used for the personalized response.                                                                  | text      |
| Content Object Record ID      | `ContentObjectRecordId`          | Record ID associated with this DMO.                                                                               | text      |
| Unique Profile Count          | `UniqueProfileCount__c`          | Total number of unique Personalization profiles (visitors) that viewed the personalized content.                  | number    |
| Personalization Request Count | `PersonalizationRequestCount__c` | Total number of Personalization requests associated with the personalized content.                                | number    |
| Attributed Clicks             | `AttributedClickCount__c`        | Number of clicks attributed to a particular stage in the defined personalization process.                         | number    |
| Attributed Orders             | `AttributedOrderCount__c`        | Number of orders attributed to a particular stage in the defined personalization process.                         | number    |
| Attributed Carts              | `AttributedCartsCount__c`        | Number of carts containing items at a particular stage in the defined personalization process.                    | number    |
| Attributed Views              | `AttributedViewsCount__c`        | Number of content views attributed to a particular stage in the defined personalization process.                  | number    |
| Attributed Revenue            | `AttributedRevenue__c`           | Revenue attributed to the personalization point.                                                                  | number    |
| Attributed Orders Placed      | `AttributedOrdersPlaced__c`      | Number of placed orders attributed to a particular stage in the defined personalization process.                  | number    |

<!-- document id=5cdd790de3b841353c062980b3be168047c2d38dcc38f28569b562be8bcdc033 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/personalization-content-click-attribution.md -->

# Personalization Content Last Touch View-Based Attribution DMO

The Personalization Content Last Touch View-Based Attribution Data Model Object (DMO) captures last-touch engagement data attributed to viewing personalized content. The data is aggregated by content.

## Object API Name

`PersnlContentLastTouchViewAttr__dlm`

## Primary Key

Personalization Attribution Primary Key (`PersonalizationAttrPk__c`)

## All Fields

| Field Name                    | Field API Name                   | Description                                                                                                       | Data Type |
| ----------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------- |
| Internal Organization         | `InternalOrganization__c`        | Reference ID to the business unit or other internal organization that owns the business account.                  | text      |
| Data Source                   | `DataSource__c`                  | Reference ID for the logical name for a system that is the source of records identified by an external record ID. | text      |
| Data Source Object            | `DataSourceObject__c`            | Reference ID for the logical name of the object where this record came from.                                      | text      |
| Attribution Date              | `PersonalizationAttrDate__c`     | Date and time that the attribution occurred.                                                                      | dateTime  |
| Data Space                    | `DataSpace__c`                   | The data space associated with this DMO                                                                           | text      |
| Root Personalization Point    | `RootPersonalizationPoint__c`    | Personalization point where the attribution occurred.                                                             | text      |
| Personalization Decision      | `PersonalizationDecision__c`     | Personalization Decision associated with the Personalization point.                                               | text      |
| Personalizer                  | `Personalizer__c`                | Personalizer used for the personalized response.                                                                  | text      |
| Content Object Record ID      | `ContentObjectRecordId`          | Record ID associated with this DMO.                                                                               | text      |
| Unique Profile Count          | `UniqueProfileCount__c`          | Total number of unique Personalization profiles (visitors) that interacted with the Personalization Point.        | number    |
| Personalization Request Count | `PersonalizationRequestCount__c` | Total number of Personalization requests launched from the Personalization Point.                                 | number    |
| Attributed Clicks             | `AttributedClickCount__c`        | Number of clicks attributed to a particular stage in the defined personalization process.                         | number    |
| Attributed Orders             | `AttributedOrderCount__c`        | Number of orders attributed to a particular stage in the defined personalization process.                         | number    |
| Attributed Carts              | `AttributedCartsCount__c`        | Number of carts attributed to a particular stage in the defined personalization process.                          | number    |
| Attributed Revenue            | `AttributedRevenue__c`           | Revenue attributed to the personalization point.                                                                  | number    |
| Attributed Orders Placed      | `AttributedOrdersPlaced__c`      | Number of placed orders attributed to a particular stage in the defined personalization process.                  | number    |

<!-- document id=37a8a8b756f5424996b05a51e0179eebe382167b3aa8bb71e3cc495554a9746e url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/data-model-object-reference.md -->

# Personalization Data Model Objects

The Personalization Data Model subject area includes multiple data model objects (DMOs) that store Personalization decision activities and experiment data.

<!--![](https://resources.help.salesforce.com/images/35726af40fea734971c6647adbae967d.png)-->

Personalization pipeline DMOs include design-time and run-time objects. These pipeline objects accumulate run-time data specific to the Personalization request process. They define where personalizations appear, eligibility for receiving personalized content, and how to present content to users or site visitors.

| Pipeline DMO                                                    | Description                                                                                                                                                                                                       |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Personalization Point DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalization-point-dmo.md)       | Gathers the information for generating and presenting personalized content. This information includes eligibility, content decisions, and presentation.                                                           |
| [Personalization Decision DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalization-decision-dmo.md) | Enables decisioning to determine Personalization eligibility and present personalized content.                                                                                                                    |
| [Personalization Schema DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalization-schema-dmo.md)     | Defines options for decision configuration and presentation and how each decision response appears.                                                                                                               |
| [Personalizer DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalizer-dmo.md)                         | Determines whether to call an additional service at run-time to retrieve the information for a complete decision response, for example, calling a recommender service to retrieve targeted, personalized content. |
| [Personalization Log DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalization-log-dmo.md)           | Gathers pipeline operational and attribution data associated with a Personalization engagement.                                                                                                                   |

Personalization attribution DMOs record the attributed data for a personalization point and the content that the model recommended. This data is essential to understanding how effective personalized content is on a customer's behavior and purchases. For example, in a commerce implementation, you can attribute engagement to revenue directly associated with a specific personalization point.

| Attribution DMO                                                                                                   | Description                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Personalization Point First Touch View-Based Attribution DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalization-point-view-attribution-dmo.md)     | Determines attribution based on whether an individual is eligible to receive personalization content from a personalization point.                                                                                                                                         |
| [Personalization Content First Touch View-Based Attribution DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalization-content-view-attribution-dmo.md) | Determines attribution based on whether an individual views personalized content presented at a personalization point.                                                                                                                                                     |
| [Personalization Point Last Touch View-Based Attribution DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalization-point-click-attribution-dmo.md)     | Determines attribution based on how individuals engage with a personalization point. For example, an amount of revenue is attributed directly to engaging with a personalization point grid component on a specific page.                                                  |
| [Personalization Content Last Touch View-Based Attribution DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalization-content-click-attribution.md)     | Determines attribution based on specific content provided in a personalized engagement. For example, a visitor to a website is presented with several recommendations. The visitor's clicks and purchases are attributed to the personalized content that they were shown. |

Experiment DMOs record the metadata and performance of personalization experiments. This data provides insights about the personalization strategies that are most effective and drive desired business outcomes.

| Experiment DMO                                                            | Description                                                                                                                                                                  |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Experiment DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/experiment-dmo.md)                                       | Defines the core metadata of an experiment, such as its name, description, state, start and stop times, and primary metrics.                                                 |
| [Experiment Cohort DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/experiment-cohort-dmo.md)                         | Defines the metadata of different cohorts within an experiment, including control and treatment groups, their allocation weights, and associated personalization details.    |
| [Experimentation Log DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/experimentation-log-dmo.md)                     | Gathers data from individual personalization experiment events.                                                                                                              |
| [Experimentation Summary DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/experimentation-summary-dmo.md)             | Captures the aggregated summary of your experiments. This DMO includes key metrics, participant counts, and statistical analysis results for overall experiment performance. |
| [Experimentation Daily Summary DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/experimentation-daily-summary-dmo.md) | Captures the daily aggregated summary of your experiments, offering a day-by-day view of performance metrics and participant engagement.                                     |

The Batch Personalization output DMO records the output created for a batch personalization. This data provides information about the decisions created against a segment and personalization point. The DMO output can then be sent to other systems, like MCE, using Data Cloud DMO Activations.

| Batch Personalization DMO                                               | Description                                                 |
| ----------------------------------------------------------------------- | ----------------------------------------------------------- |
| [Batch Personalization Output DMO](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/batch-personalization-output-dmo.md) | Captures the decisions created for a batch personalization. |

<!-- document id=e20999a7f54027678e2f3171025cc99b207d26b358b819eb7308b52c3f76d5e0 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/personalization-decision-dmo.md -->

# Personalization Decision DMO

The Personalization Decision Data Model Object (DMO) defines all object properties required to make personalized decisions for a Personalization point. Properties include eligibility criteria (targeting rules), priority settings, and so on.

## Object API Name

`PersonalizationDecision__dlm`

## Primary Key

Personalization Decision (`Id__c`)

## All Fields

| Field Name            | Field API Name                       | Description                                                           | Data Type |
| --------------------- | ------------------------------------ | --------------------------------------------------------------------- | --------- |
| Developer Name        | `DeveloperName__c`                   | Name of the personalization decision in a code-friendly format.       | text      |
| Name                  | `Name__c`                            | Name applied to the Personalization Decision.                         | text      |
| Description           | `Description__c`                     | Optional description for the Personalization Decision.                | text      |
| Personalization Point | `PersonalizationPointId__c`          | Personalization point using the decision.                             | text      |
| Personalizer          | `PersonalizerId__c`                  | Name applied to the associated Personalizer.                          | text      |
| Priority              | `PersonalizationDecisionPriority__c` | Priority value assigned to the decision at the Personalization Point. | number    |
| Criteria              | `Criteria__c`                        | Targeting rules associated with the personalization decision.         | text      |
| Last Modified Date    | `LastModifiedDate__c`                | The date when a user last modified the record.                        | dateTime  |
| Created Date          | `CreatedDate__c`                     | The date a record was created.                                        | dateTime  |

<!-- document id=9a8a41a23b01a679986ba7f86d17420553b2202af2579337f794dbea571a385a url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/invocable-actions.md -->

# Personalization Invocable Actions

<!-- document id=a16dccae5f1c20dd10efba7aea923edfb987ad2038384dee0a591a1e0405a5d4 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/personalization-log-dmo.md -->

# Personalization Log DMO

The Personalization Log Data Model Object (DMO) captures data from various data sources about engagement with Personalization.

## Object API Name

`PersonalizationLog__dlm`

## Primary Key

Personalization Log Id (`Id__c`)

## All Fields

| Field Name                      | Field API Name                    | Description                                                                                                                                                                                              | Data Type |
| ------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| Personalization Content Id      | `PersonalizationContentId__c`     | Personalization content record ID for the content provided.                                                                                                                                              | text      |
| Personalization Id              | `PersonalizationId__c`            | Identifier for the personalized response sent to a specific personalization point.                                                                                                                       | text      |
| Personalization Request Id      | `PersonalizationRequestId__c`     | Unique identifier for the Personalization request.                                                                                                                                                       | text      |
| Request Start DateTime          | `RequestStartDateTime__c`         | Date and time the Personalization request was made.                                                                                                                                                      | dateTime  |
| Augmenting Stage Time Millis    | `AugmentingStageTimeMillis__c`    | Amount of time, in milliseconds, it took to look up and augment a profile.                                                                                                                               | number    |
| Qualifying Stage Time Millis    | `QualifyingStageTimeMillis__c`    | Amount of time, in milliseconds, it took to qualify a profile for a Personalization response.                                                                                                            | number    |
| Personalizing Stage Time Millis | `PersonalizingStageTimeMillis__c` | Amount of time, in milliseconds, it took to retrieve content for all personalization decisions.                                                                                                          | number    |
| Response Time Millis            | `ResponseTimeMillis__c`           | Amount of time, in milliseconds, it took to respond to the Personalization request.                                                                                                                      | number    |
| Individual                      | `IndividualId__c`                 | Individual DMO ID.                                                                                                                                                                                       | text      |
| Personalization Type            | `PersonalizationType__c`          | The type of personalization presented to the visitor. For example, Recommendations or Manual Content.                                                                                                    | text      |
| Personalization Point Id        | `PersonalizationPointId`          | The ID of the personalization point in the personalization request.                                                                                                                                      | text      |
| Personalization Decision Id     | `PersonalizationDecisionId`       | The ID of the personalization decision in the personalization request.                                                                                                                                   | text      |
| Personalizer Id                 | `PersonalizerId`                  | The ID of the personalizer used to call a personalization service, if required. The personalizer determines what service to use, gathers any other required data, and generates a personalized response. | text      |
| Content                         | `Content`                         | Raw content returned by the personalization request. For example, a data element in the array.                                                                                                           | text      |
| Content Length                  | `ContentLength`                   | Length of the content field in abstract units for use in comparative analysis.                                                                                                                           | number    |
| Number of Content Items         | `NumContentItems`                 | Number of content items returned by the personalization request.                                                                                                                                         | number    |
| DMO Label                       | `DmoLabel`                        | Label assigned to the DMO. For example, Goods Product.                                                                                                                                                   | text      |
| DMO API Name                    | `DmoApiName`                      | The DMO name in code-friendly format. For example, `ssot_GoodsProduct_dlm`.                                                                                                                              | text      |
| DMO Record Id                   | `DmoRecordId`                     | The record ID of the DMO. For example, `RedSoxBallCap`.                                                                                                                                                  |

<!-- document id=f766d3ca6640980b433db870c11b50923bd9b65579cc7e641f7d5053dee6b3f8 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/personalization-point-dmo.md -->

# Personalization Point DMO

The Personalization Point Data Model Object (DMO) defines a specific personalization experience point, like a grid location in Experience Builder, that is eligible for a personalization decision.

## Object API Name

`PersonalizationPoint__dlm`

## Primary Key

Personalization Point (`Id__c`)

## All Fields

| Field Name                   | Field API Name               | Description                                                                                                               | Data Type |
| ---------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------- |
| Developer Name               | `DeveloperName__c`           | Name of the personalization point in a code-friendly format.                                                              | text      |
| Name                         | `Name__c`                    | Name applied to the Personalization Point.                                                                                | text      |
| Description                  | `Description__c`             | Optional description for the Personalization Point.                                                                       | text      |
| Personalization Schema       | `PersonalizationSchemaId__c` | Personalization schema used by this point to define the shape of the personalized data returned by the selected decision. | text      |
| Personalization Point Status | `Status__c`                  | Current status of the personalization point. For example, Active, Processing, or Deleting.                                | text      |
| Profile Data Graph Id        | `ProfileDataGraphId__c`      | Data graph containing precomputed profile data for use by the Personalizer.                                               | number    |
| Source                       | `Source__c`                  | The Personalization source. For example, the Personalization App or Experience Builder                                    | text      |
| Last Modified Date           | `LastModifiedDate__c`        | The date when a user last modified the record.                                                                            | dateTime  |
| Created Date                 | `CreatedDate__c`             | The date the record was created.                                                                                          | dateTime  |

<!-- document id=fc48067f29b3cb53d94b31026dc362ba811aea694344f5ebca881c962b7934ae url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/personalization-point-view-attribution-dmo.md -->

# Personalization Point First Touch View-Based Attribution DMO

The Personalization Point First Touch View-Based Attribution Data Model Object (DMO) captures first-touch engagement data attributed to viewing personalized content. The data is aggregated by personalization point.

## Object API Name

`PersnlPointFirstTouchViewAttr__dlm`

## Primary Key

Personalization Attribution Primary Key (`PersonalizationAttrPk__c`)

## All Fields

| Field Name                    | Field API Name                   | Description                                                                                                       | Data Type |
| ----------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------- |
| Internal Organization         | `InternalOrganization__c`        | Reference ID to the business unit or other internal organization that owns the business account.                  | text      |
| Data Source                   | `DataSource__c`                  | Reference ID for the logical name for a system that is the source of records identified by an external record ID. | text      |
| Data Source Object            | `DataSourceObject__c`            | Reference ID for the logical name of the object where this record came from.                                      | text      |
| Attribution Date              | `AttributionDate__c`             | Date of the first engagement that led to the attribution.                                                         | dateTime  |
| Data Space                    | `DataSpace__c`                   | Data space used as the personalization content source.                                                            | text      |
| Root Personalization Point    | `RootPersonalizationPoint__c`    | Personalization point where data was gathered.                                                                    | text      |
| Personalization Decision      | `PersonalizationDecision__c`     | Personalization decision assigned to the Personalization point.                                                   | text      |
| Personalizer                  | `Personalizer__c`                | Personalizer used for the personalized response.                                                                  | text      |
| Unique Profile Count          | `UniqueProfileCount__c`          | Total number of unique personalization profiles (visitors) that interacted with the personalization point.        | number    |
| Personalization Request Count | `PersonalizationRequestCount__c` | Total number of Personalization requests launched from the personalization point.                                 | number    |
| Attributed Clicks             | `AttributedClickCount__c`        | Number of content clicks attributed to personalization views.                                                     | number    |
| Attributed Orders             | `AttributedOrderCount__c`        | Number of orders attributed to personalization views.                                                             | number    |
| Attributed Carts              | `AttributedCartsCount__c`        | Number of add to cart actions attributed to personalization views.                                                | number    |
| Attributed Views              | `AttributedViewsCount__c`        | Number of orders attributed to personalization views.                                                             | number    |
| Attributed Revenue            | `AttributedRevenue__c`           | Revenue attributed to the personalization point.                                                                  | number    |
| Attributed Orders Placed      | `AttributedOrdersPlaced__c`      | Number of placed orders attributed to the personalization point.                                                  | number    |

<!-- document id=656afc99f1a10524410ac278c3fde5a3a758646868e7b3241012b91afc69d99b url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/personalization-point-click-attribution-dmo.md -->

# Personalization Point Last Touch View-Based Attribution DMO

The Personalization Point Last Touch View-Based Attribution Data Model Object (DMO) captures last-touch engagement data attributed to viewing personalized content. The data is aggregated by personalization point.

## Object API Name

`PersnlPointLastTouchViewAttr__dmo`

## Primary Key

Personalization Attribution Primary Key (`PersonalizationAttrPk__c`)

## All Fields

| Field Name                    | Field API Name                   | Description                                                                                                       | Data Type |
| ----------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------- |
| Internal Organization         | `InternalOrganization__c`        | Reference ID to the business unit or other internal organization that owns the business account.                  | text      |
| Data Source                   | `DataSource__c`                  | Reference ID for the logical name for a system that is the source of records identified by an external record ID. | text      |
| Data Source Object            | `DataSourceObject__c`            | Reference ID for the logical name of the object where this record came from.                                      | text      |
| Attribution Date              | `AttributionDate__c`             | Date of the first engagement that led to the attribution.                                                         | dateTime  |
| Data Space                    | `DataSpace__c`                   | The data space associated with this DMO                                                                           | text      |
| Personalization Point         | `PersonalizationPoint__c`        | Personalization point where the attribution occurred.                                                             | text      |
| Personalization Decision      | `PersonalizationDecision__c`     | Personalization Decision associated with the Personalization point.                                               | text      |
| Personalizer                  | `Personalizer__c`                | Personalizer used for the personalized response.                                                                  | text      |
| Unique Profile Count          | `UniqueProfileCount__c`          | Total number of unique Personalization profiles (visitors) that interacted with the Personalization Point.        | number    |
| Personalization Request Count | `PersonalizationRequestCount__c` | Total number of Personalization requests launched from the Personalization Point.                                 | number    |
| Attributed Clicks             | `AttributedClicksCount__c`       | Number of clicks on personalized content.                                                                         | number    |
| Attributed Carts              | `AttributedCartsCount__c`        | Number of add to cart actions attributed to personalization clicks.                                               | number    |
| Attributed Revenue            | `AttributedRevenue__c`           | Revenue attributed to the personalization point.                                                                  | number    |
| Attributed Orders Placed      | `AttributedOrdersPlaced__c`      | Number of orders attributed to clicks on personalized content.                                                    | number    |

<!-- document id=53e2b94c45c8951354113a8814f860984848a0dbecead4c7fa112ef8add62012 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/personalization-schema-dmo.md -->

# Personalization Schema DMO

The Personalization Schema Data Model Object (DMO) defines how personalized results are presented to visitors. For example, the schema can present personalized results as a list of product recommendations, or present manually-defined information, like specific record data, a call to action banner, or an image.

## Object API Name

`PersonalizationSchema__dlm`

## Primary Key

Personalization Schema (`Id__c`)

## All Fields

| Field Name           | Field API Name           | Description                                                                                           | Data Type |
| -------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------- | --------- |
| Name                 | `Name__c`                | Name applied to the Personalization Schema.                                                           | text      |
| Description          | `Description__c`         | Optional description for the Personalization Schema.                                                  | text      |
| Personalization Type | `PersonalizationType__c` | The type of personalization presented to the visitor. For example, Recommendations or Manual Content. | text      |
| Content Object       | `ContentObject__c`       | The logical name of the object where the personalized content originated.                             | text      |
| Last Modified Date   | `LastModifiedDate__c`    | The date when a user last modified the record.                                                        | dateTime  |
| Created Date         | `CreatedDate__c`         | The date a record was created.                                                                        | dateTime  |

<!-- document id=c99d2ae63402e993ecabef04a9c618dd907fba67f4325b3fcaafdc1f3f37ce6c url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/mobile-integration/configure-mobile-personalization/personalize-mobile-experiences.md -->

# Personalize Mobile Experiences

The Personalization module of the Engagement Mobile SDK enables you to query the Personalization service and receive targeted content within your iOS and Android applications.

While the Personalization module processes these requests to return personalized content, the Data 360 module handles the capture of customer interactions. By integrating both modules, you can send engagement data to Data 360 to build behavior profiles and use that data to drive real-time personalization decisions in your app.

## Prerequisites

The Personalization module depends on the underlying Data 360 module for identity resolution, consent management, and behavioral data collection. Therefore, integrate your mobile app with the Data 360 module. For procedure, see [Data 360 Engagement Mobile SDK](https://developer.salesforce.com/docs/data/data-cloud-engagement-mobile-sdk/guide/c360a-api-engagement-mobile-sdk.html).

**note:** The Engagement Mobile SDK provides methods to capture interactions and personalize content. Call these methods in your application's code at the appropriate moments in the user journey to track events and retrieve personalized experiences.

## Pro-Code Mobile Personalization

Pro-code integration gives you full control over the Decisioning API. You write native iOS or Android code to call `fetchDecisions()` directly, parse responses, track engagement, and render personalized content in your own UI components. For more information, see [Pro-Code Mobile Personalization](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-procode.md).

- [iOS Integration](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-ios.md)
- [Android Integration](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-android.md)

## Low-Code Mobile Personalization

Low-code integration uses pre-built SDK plugins that handle fetching, rendering, and engagement tracking for you. Drop a `ContentZone` component into your app, configure it with the content zone identifier, and the SDK takes care of the rest for out-of-the-box components. Custom components and custom styling require additional setup. For more information, see [Low-Code Mobile Personalization](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-lowcode.md).

- [iOS Integration](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-lowcode-ios.md)
- [Android Integration](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-lowcode-android.md)
- [React Native Integration](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-lowcode-reactnative.md)
- [Flutter Integration](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-lowcode-flutter.md)

## Low-Code vs. Pro-Code

Both paths build on the same underlying SDKs. Use this comparison to choose the approach that fits your use case:

|                         | Low-code                                                                                                                                                                             | Pro-code                                                                                                 |
| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |
| **Rendering**           | Built-in (Banner, Recommendations) or custom components                                                                                                                              | Fully custom - you build the UI                                                                          |
| **Engagement tracking** | Automatic for out-of-the-box components, assisted for custom components (the SDK provides tracking APIs)                                                                             | Manual                                                                                                   |
| **Setup effort**        | Lower                                                                                                                                                                                | Higher                                                                                                   |
| **Flexibility**         | High - override any component or build your own, and change the personalization point or content served at any time without code changes, within the components allowed by that zone | Full control at code time, but low flexibility at runtime                                                |
| **Best for**            | Standard content zones, rapid integration - custom components can also handle highly custom layouts                                                                                  | Multiple personalization points in a single request, or a zone lifecycle that isn't tied to UI rendering |

<!-- document id=25584a314dcfd82bb62d6ddd6cd7d89ed518f0bb50d0228548376ddd66c3d188 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/web-integration/personalize-web-experiences.md -->

# Personalize Web Experiences with the Salesforce Interactions SDK

Salesforce Interactions SDK enables you to capture customer interactions on your website and send that data to Data Cloud. In Data Cloud, you can use this data to build behavior profiles for website visitors, segment audiences, or integrate that data with other Salesforce products. 

You can also use the Interactions SDK to send customer interactions to Personalization as requests through the Decisioning API. Personalization processes these requests and returns personalized content that you can render and display on specific areas of your website. 

The SDK uses the `SalesforceInteractions` namespace, which encapsulates its core components. Personalization extends this namespace with the `Personalization` object, providing methods and functions to interact with its features.

<!-- document id=3bc70c836a51b8ac82180a0ebed5a12a9a1d654aa8122d6abac9042e92a52c56 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/data-model-objects/personalizer-dmo.md -->

# Personalizer DMO

The Personalizer Data Model Object (DMO) defines what additional service is used to provide a complete decision response. For example, to provide a recommendations response, the personalizer uses the recommendation service to provide targeted, personalized results to visitors.

## Object API Name

`Personalizer__dlm`

## Primary Key

Personalizer (`Id__c`)

## All Fields

| Field Name            | Field API Name          | Description                                                                                              | Data Type |
| --------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- | --------- |
| Name                  | `Name__c`               | Name applied to the Personalizer.                                                                        | text      |
| Developer Name        | `DeveloperName__c`      | Name of the Personalizer in a code-friendly format.                                                      | text      |
| Master Label          | `MasterLabel__c`        | Primary setup object name.                                                                               | text      |
| Description           | `Description__c`        | Optional description for the Personalizer.                                                               | text      |
| Content Object Id     | `ContentObjectId__c`    | The logical name of the object where the personalized content originated.                                | text      |
| Catalog Data Graph Id | `CatalogDataGraphId__c` | Identifier for the data graph containing precomputed catalog data for use by the Personalizer.           | text      |
| Profile Data Graph Id | `ProfileDataGraphId__c` | Data graph containing precomputed profile data for use by the Personalizer.                              | text      |
| Strategy              | `Strategy__c`           | Recommendation strategy selected for this personalization. For example, Top Sellers or Maximize Revenue. | text      |
| Last Modified Date    | `LastModifiedDate__c`   | The date when a user last modified the record.                                                           | dateTime  |
| Created Date          | `CreatedDate__c`        | The date a record was created.                                                                           | dateTime  |

<!-- document id=218dc74f13385b29be6778660ffc36f83f50eb2ce542bbc60fabb7ac9eac0d55 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/mobile-integration/configure-mobile-personalization/personalize-mobile-experiences-procode.md -->

# Pro-Code Mobile Personalization

Pro-code mobile personalization gives you full control over the Decisioning API. Instead of using a pre-built SDK plugin, you call `fetchDecisions()` directly, parse the response, and render personalized content in your own UI - and you're responsible for reporting engagement yourself.

## How It Works

1. The host app initializes the native Data 360 and Personalization modules of the Unified SDK on startup.
2. You call `fetchDecisions()` with the personalization point API Name(s) you want content for.
3. The SDK requests a decision from the backend and returns a `DecisionsResponse`.
4. You parse the response and render your own UI with the returned content.
5. You report `View` and `Click` engagement manually using the SDK's tracking APIs.

## Prerequisites

Pro-code integration depends on the same underlying native SDKs as the low-code path. Before integrating:

- Complete the [Data 360 Engagement Mobile SDK](https://developer.salesforce.com/docs/data/data-cloud-engagement-mobile-sdk/guide/c360a-api-engagement-mobile-sdk.html) setup for identity, consent, and behavioral data collection.
- Configure a Mobile Connector in Data 360 and obtain your **CDP_APP_ID** and **CDP_ENDPOINT** from your Data Cloud administrator.

## Platform Guides

- [iOS Integration](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-ios.md)
- [Android Integration](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences-android.md)

## When to use

Pro-code integration is best when you need multiple personalization points in a single request, or a zone lifecycle that isn't tied to UI rendering. For a full comparison, see [Low-Code vs. Pro-Code](https://developer.salesforce.com/docs/marketing/einstein-personalization/guide/personalize-mobile-experiences.md#low-code-vs-pro-code).

<!-- document id=329cdc104498d51ac1d56a3a2ea1eaac5126ea03bb14cb178ca2da77228ccf51 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/mobile-integration/configure-mobile-personalization/personalize-mobile-experiences-lowcode-reactnative.md -->

# React Native Low-Code Integration

Use the Salesforce Personalization React Native plugin to display personalized content in your React Native app with minimal setup. The plugin provides live and mock content zones, out-of-the-box banner and recommendation renderers, identity and event APIs, preview handling, and engagement helpers for custom components.

1. [Install the SDK](#install-the-sdk)
2. [Initialize the SDK](#initialize-the-sdk)
3. [Display a Content Zone](#display-a-content-zone)
4. [Out-of-the-Box Components](#out-of-the-box-components)
5. [Custom Components](#custom-components)
6. [Engagement Tracking](#engagement-tracking)
7. [Preview](#preview)
8. [Design-Time Rendering](#design-time-rendering)
9. [Identity and Events](#identity-and-events)

## Install the SDK

```shell
npm install @salesforce-personalization/react-native-personalization
# or
yarn add @salesforce-personalization/react-native-personalization
```

Add the package. It resolves to the latest published version.

The plugin supports both React Native architectures. Autolinking and package Codegen configuration register the native bridge. Do not manually register the package or invoke Codegen only for this plugin.

### Requirements

- React Native 0.76 or later, but earlier than 1.0
- React 18.3 or React 19
- Node.js 18 or later
- iOS 15 or later
- Android API 26 or later
- Java 17 for Android builds

The compatible release must define the final Android compile SDK, target SDK, Kotlin Gradle Plugin, Gradle, and Android Gradle Plugin matrix. Do not infer those versions from the JavaScript package version.

## Initialize the SDK

The host app initializes the native SDK. There is no JavaScript `configure(...)` API. Complete both the iOS and Android platform setup below. Leave consent unset during native initialization.

### iOS setup

Add tenant configuration to the app's `Info.plist`. Add the optional CDN value only when your administrator provides an explicit override.

```xml
<key>com.salesforce.personalization.CDP_APP_ID</key>
<string>YOUR_CDP_APP_ID</string>
<key>com.salesforce.personalization.CDP_ENDPOINT</key>
<string>YOUR_CDP_ENDPOINT_HOST</string>
<key>com.salesforce.personalization.DATASPACE</key>
<string>default</string>
```

Install the native dependencies after the compatible package is available.

```shell
cd ios
pod install
```

Merge the following helper into the existing `AppDelegate.swift`. Keep the app's generated React Native setup, module name, bundle URL, initial properties, and other delegate methods.

```swift
import SFMCSDK
import Cdp
import Personalization

private func initializePersonalizationSDK() {
  let info = Bundle.main.infoDictionary ?? [:]
  let appId = info["com.salesforce.personalization.CDP_APP_ID"] as? String ?? ""
  let endpoint = info["com.salesforce.personalization.CDP_ENDPOINT"] as? String ?? ""
  let dataspace = info["com.salesforce.personalization.DATASPACE"] as? String ?? "default"
  if appId.isEmpty || appId.hasPrefix("YOUR_") ||
     endpoint.isEmpty || endpoint.hasPrefix("YOUR_") {
    NSLog("Personalization is not configured; SDK init skipped")
    return
  }

  let cdpConfig = CdpConfigBuilder(appId: appId, endpoint: endpoint)
    .trackScreens(false)
    .trackLifecycle(false)
    .build()
  let personalizationConfig = PersonalizationConfigBuilder()
    .dataspace(dataspace)
    .build()
  let sdkConfig = ConfigBuilder()
    .setCdp(config: cdpConfig)
    .setPersonalization(config: personalizationConfig)
    .build()
  SFMCSdk.initializeSdk(sdkConfig) { statuses in
    statuses.forEach { print("\($0.moduleName.rawValue): \($0.initStatus.rawValue)") }
  }
}
```

Call `initializePersonalizationSDK()` once from the existing `application(_:didFinishLaunchingWithOptions:)` before returning. This example disables automatic screen and lifecycle tracking. Choose those settings according to your app's tracking policy.

### Android setup

The compatible release must publish validated Android build versions. The reviewed source expects at least API 26 and Java 17 and currently resolves a Personalization 3.x dependency dynamically. Its source and example Kotlin versions do not establish a safe customer compatibility guarantee. Treat any Kotlin metadata error as a release compatibility issue, not as a reason to blindly upgrade one build plugin.

Declare the Salesforce Maven repositories in the host app. Library repository declarations are not inherited by consuming apps.

```
repositories {
  google()
  mavenCentral()
  maven {
    url "https://salesforce-marketingcloud.github.io/MarketingCloudSDK-Android/repository"
  }
  maven {
    url "https://salesforce-marketingcloud.github.io/mobile-sdk-cdp-android/repository"
  }
  maven {
    url "https://salesforce-marketingcloud.github.io/Personalization-Android/repository"
  }
}
```

Use the location that matches the app's repository policy. If repositories are centralized in `settings.gradle`, use `RepositoriesMode.PREFER_SETTINGS`. Do not use `FAIL_ON_PROJECT_REPOS` with a plugin release that still declares project-level repositories. Do not add the native Personalization dependency directly; the plugin exposes it transitively.

Ensure release builds have network access and place configuration metadata inside the application element.

```xml
<uses-permission android:name="android.permission.INTERNET" />

<application>
  <meta-data
    android:name="com.salesforce.personalization.CDP_APP_ID"
    android:value="YOUR_CDP_APP_ID" />
  <meta-data
    android:name="com.salesforce.personalization.CDP_ENDPOINT"
    android:value="YOUR_CDP_ENDPOINT_HOST" />
  <meta-data
    android:name="com.salesforce.personalization.DATASPACE"
    android:value="default" />
</application>
```

Add optional CDN metadata only when your administrator supplies an override. Merge this helper into the existing `MainApplication` class and call it once from `onCreate()` after `super.onCreate()`.

```kotlin
import android.content.pm.PackageManager
import com.salesforce.marketingcloud.cdp.CdpConfig
import com.salesforce.marketingcloud.sfmcsdk.SFMCSdk
import com.salesforce.marketingcloud.sfmcsdk.SFMCSdkModuleConfig
import com.salesforce.personalization.PersonalizationConfig

private fun initializePersonalizationSDK() {
  val metaData = packageManager
    .getApplicationInfo(packageName, PackageManager.GET_META_DATA)
    .metaData
  val appId = metaData.getString("com.salesforce.personalization.CDP_APP_ID").orEmpty()
  val endpoint = metaData.getString("com.salesforce.personalization.CDP_ENDPOINT").orEmpty()
  val dataspace = metaData.getString("com.salesforce.personalization.DATASPACE") ?: "default"
  if (appId.isBlank() || appId.startsWith("YOUR_") ||
      endpoint.isBlank() || endpoint.startsWith("YOUR_")) {
    android.util.Log.w("PersonalizedApp", "Personalization is not configured; SDK init skipped")
    return
  }
  val cdpConfig = CdpConfig.Builder(this, appId, endpoint).build()
  val personalizationConfig = PersonalizationConfig.Builder(this)
    .dataspace(dataspace)
    .build()
  SFMCSdk.configure(this, SFMCSdkModuleConfig.build {
    cdpModuleConfig = cdpConfig
    personalizationModuleConfig = personalizationConfig
  }) {}
}
```

Apps using the New Architecture must follow their React Native version's normal clean-build flow. The reviewed guide has not established Android's default automatic screen and lifecycle collection behavior for the pinned native SDK. Verify that behavior and document the supported pre-consent opt-out calls before publication.

## Display a Content Zone

With the SDK initialized, place a `ContentZone` in your UI. The JavaScript factory names are `SalesforceBanner` and `SalesforceRecommendations`. Their backend experience template names remain `Salesforce_Banner` and `Salesforce_Recommendations`.

After adding a ContentZone to your app code, create the matching content zone record in Salesforce Personalization. See [Set Up Mobile Content Zones](https://help.salesforce.com/s/articleView?id=mktg.persnl_experience_mobile_content_zones_register.htm) for instructions on defining personalization points, assigning components, and configuring engagement definitions.

```tsx
import {
  ContentZone,
  SalesforceBanner,
  SalesforceRecommendations,
} from "@salesforce-personalization/react-native-personalization";

const homeComponents = [SalesforceBanner(), SalesforceRecommendations()];

export function HomePersonalization() {
  return <ContentZone name="HomeScreen" allowedComponents={homeComponents} fallback={() => null} />;
}
```

The principal props are:

- `name`: Required nonblank content zone identifier.
- `allowedComponents`: Required component instances with unique normalized names.
- `loading`: Optional UI displayed during initial loading.
- `fallback`: Optional error renderer. Do not expose error details to customers.
- `timeoutSeconds`: Positive request timeout. The default is 10 seconds.
- `controller`: Programmatic refresh controller. Use one per mounted zone.
- `decisionsRequestContext`: Context used by the next decision request.

Component names are trimmed and lowercased for matching. Do not place two instances with the same normalized component name in one zone - duplicates are not rejected, the last one silently wins. The live zone captures `allowedComponents` when it mounts, so remount the zone to replace the component contract. Changing timeout or decision context alone does not fetch; the next refresh uses the latest values.

### Apply consent

Do not mount a live content zone until native opt-in succeeds. On opt-out, unmount live zones immediately, then await the native opt-out call. If opt-out fails, keep zones unmounted and present a retry path. Persist a choice only after the native call succeeds.

```tsx
import { useState } from "react";
import { Button, Text, View } from "react-native";
import {
  ContentZone,
  PersonalizationModule,
  SalesforceBanner,
} from "@salesforce-personalization/react-native-personalization";

type ConsentState = "unknown" | "optedIn" | "optedOut";
const homeComponents = [SalesforceBanner()];
export function ConsentGate({
  initialChoice,
  saveChoice,
}: {
  initialChoice: boolean | null;
  saveChoice: (optIn: boolean) => Promise<void>;
}) {
  const [consent, setConsent] = useState<ConsentState>(
    initialChoice === null ? "unknown" : initialChoice ? "optedIn" : "optedOut",
  );
  const [updating, setUpdating] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const updateConsent = async (optIn: boolean) => {
    if (updating) return;
    const previous = consent;
    setUpdating(true);
    setError(null);
    if (!optIn) setConsent("optedOut");
    try {
      await PersonalizationModule.setConsent(optIn);
      setConsent(optIn ? "optedIn" : "optedOut");
      try {
        await saveChoice(optIn);
      } catch {
        if (optIn) {
          await PersonalizationModule.setConsent(false);
          setConsent("optedOut");
        }
        setError("Consent was applied, but the preference could not be saved.");
      }
    } catch {
      setConsent(previous);
      setError("The consent choice could not be applied. Try again.");
    } finally {
      setUpdating(false);
    }
  };
  return (
    <View>
      {consent === "optedIn" ? (
        <ContentZone name="HomeScreen" allowedComponents={homeComponents} />
      ) : (
        <Text>Personalized content is not displayed.</Text>
      )}
      {error ? <Text accessibilityRole="alert">{error}</Text> : null}
      {updating ? <Text accessibilityLiveRegion="polite">Updating choice</Text> : null}
      <Button
        disabled={updating}
        title="Allow personalization"
        onPress={() => void updateConsent(true)}
      />
      <Button
        disabled={updating}
        title="Turn off personalization"
        onPress={() => void updateConsent(false)}
      />
    </View>
  );
}
```

`isConsentOptIn()` returns false for both unset consent and explicit opt-out. Persist the explicit user choice separately when the app must distinguish those states. Hydrate that choice before rendering this gate and reconcile a saved opt-in with `isConsentOptIn()` at startup. A consent change does not automatically retry a prior content request.

## Out-of-the-Box Components

The built-in `SalesforceBanner` and `SalesforceRecommendations` renderers handle rendering and engagement tracking automatically. Their backend experience template names are `Salesforce_Banner` and `Salesforce_Recommendations`.

Banner responses require nonblank `header` and `imageUrl` strings. A banner is actionable when it has an app `onTap` callback or a nonblank `ctaUrl`. The app callback takes precedence over default URL opening.

Recommendation responses require a nonempty `items` array. Every usable item requires nonblank `id`, `name`, and `imageUrl` strings. Production responses must also provide unique IDs, but this source version does not enforce or remove duplicates. Duplicate IDs become duplicate React Native list keys and produce undefined rendering behavior.

The plugin removes individually invalid recommendation items. This is only a display-resilience feature. It does not remap engagement payload indices, so a removed item can cause later View and Click events to be attributed to the wrong item. Serve only valid, unique items in their original order.

### Handle URLs safely

Personalized image, CTA, and preview URLs cross a trust boundary. The built-in renderers warn about malformed URLs but do not enforce your app's trusted hosts. Use trusted campaign configuration and override CTA handling with `onTap` when the app must enforce navigation policy.

Parse URLs and allow only an explicit scheme, host, port, and closed-form path. Decide explicitly whether query strings and fragments are permitted. Do not use substring matching or raw prefix matching for security decisions.

```tsx
import { Linking } from "react-native";
import { SalesforceBanner } from "@salesforce-personalization/react-native-personalization";

function isTrustedCta(rawUrl: string): boolean {
  try {
    const url = new URL(rawUrl);
    const path = decodeURIComponent(url.pathname);
    return (
      url.protocol === "https:" &&
      url.hostname.toLowerCase() === "shop.example.com" &&
      url.port === "" &&
      url.username === "" &&
      url.password === "" &&
      url.search === "" &&
      url.hash === "" &&
      /^\/products\/[A-Za-z0-9_-]+$/.test(path)
    );
  } catch {
    return false;
  }
}

const secureBanner = SalesforceBanner({
  onTap: async ({ ctaUrl }) => {
    if (!ctaUrl || !isTrustedCta(ctaUrl)) return;
    await Linking.openURL(ctaUrl);
  },
});
```

Apply equivalent HTTPS host and path allowlists to image URLs in a custom renderer. Do not permit `javascript`, `data`, `file`, arbitrary custom schemes, or attacker-controlled redirect hosts. Review trusted paths so a valid host cannot route users to an unintended endpoint.

## Custom Components

Custom components can reuse an existing backend experience template. Put React Hooks in the React component returned by `compose`, not directly in `compose`.

```tsx
import type {
  Component,
  ComponentContext,
  ComponentModel,
} from "@salesforce-personalization/react-native-personalization";
import {
  EngagementAction,
  trackEngagement,
  useTrackEngagementViewOnce,
} from "@salesforce-personalization/react-native-personalization";
import { Image, Pressable, Text } from "react-native";

interface ProductCardModel extends ComponentModel {
  header: string;
  imageUrl: string;
}
function ProductCardView({
  model,
  context,
}: {
  model: ProductCardModel;
  context: ComponentContext;
}) {
  useTrackEngagementViewOnce(context);

  const handlePress = () => {
    trackEngagement(context, EngagementAction.click);
  };
  return (
    <Pressable
      accessibilityRole="button"
      accessibilityLabel={model.header}
      onPress={handlePress}
      style={{ minHeight: 48 }}
    >
      <Image
        accessible={false}
        source={{ uri: model.imageUrl }}
        style={{ width: "100%", height: 200 }}
      />
      <Text>{model.header}</Text>
    </Pressable>
  );
}
export function ProductCard(): Component<ProductCardModel> {
  return {
    name: "Salesforce_Banner",
    validateAndCreateComponentModel: (json) => {
      const value: unknown = JSON.parse(json);
      if (typeof value !== "object" || value === null) {
        throw new Error("ProductCard requires an object");
      }
      const record = value as Record<string, unknown>;
      if (
        typeof record.header !== "string" ||
        record.header.trim() === "" ||
        typeof record.imageUrl !== "string" ||
        record.imageUrl.trim() === ""
      ) {
        throw new Error("ProductCard requires nonblank header and imageUrl");
      }
      let imageUrl: URL;
      try {
        imageUrl = new URL(record.imageUrl);
      } catch {
        throw new Error("ProductCard image URL is invalid");
      }
      if (
        imageUrl.protocol !== "https:" ||
        imageUrl.hostname !== "images.example.com" ||
        imageUrl.port !== ""
      ) {
        throw new Error("ProductCard requires nonblank header and imageUrl");
      }
      return {
        header: record.header,
        imageUrl: record.imageUrl,
      };
    },
    compose: (model, context) => <ProductCardView model={model} context={context} />,
  };
}
```

Treat `ComponentContext` and all nested engagement data as opaque. TypeScript readonly fields are compile-time protection only. Do not mutate the context, copy it, spread it, reconstruct it, or copy nested engagement payloads. Pass the exact object received from `compose` to every engagement helper. View dedup uses that object's identity, not `personalizationId`; a copy creates a new dedup scope.

## Engagement Tracking

Before engagement events are recorded, ensure your engagement definitions (View, Click) are configured in the Data 360 mobile connector. See [Set Up Mobile Engagement Tracking](https://help.salesforce.com/s/articleView?id=mktg.persnl_experience_mobile_engagement_tracking.htm) for instructions on defining engagement actions alongside your components and content zones.

Out-of-the-box components track `View` and `Click` automatically. For custom components:

For a single element, use `useTrackEngagementViewOnce(context)` for View and `trackEngagement(context, action)` for repeatable actions such as Click. For a `FlatList` or `VirtualizedList`, attach the handler returned by `useTrackEngagementViewOncePerItem(context)` and use `trackEngagementPerItem(context, index, action)` for repeatable item actions. Merely calling the hook does not report item Views.

```tsx
import { FlatList, type ListRenderItem } from 'react-native'
import type { ComponentContext } from '@salesforce-personalization/react-native-personalization'
import { useTrackEngagementViewOncePerItem } from '@salesforce-personalization/react-native-personalization'

export function RecommendationList<T>({ context, items, renderItem }: {
  context: ComponentContext
  items: readonly T[]
  renderItem: ListRenderItem<T>
}) {
  const onViewableItemsChanged = useTrackEngagementViewOncePerItem(context)
  return <FlatList
    data={items}
    renderItem={renderItem}
    onViewableItemsChanged={onViewableItemsChanged}
    viewabilityConfig={{ itemVisiblePercentThreshold: 50 }}
  />
}
```

Per-item engagement uses one unchanged, zero-based, flat serving index. Do not filter, sort, insert, group, or use section-relative indices before tracking. If UI transformation is unavoidable, retain and pass each item's original flat serving index. Do not pass a `SectionList` row index directly because it restarts in every section.

## Preview

Preview URLs contain a token. Treat the complete URL and token as sensitive. Do not log, persist, add to analytics, include in crash breadcrumbs, or transmit them to any service other than the SDK preview handler.

The reviewed Android bridge logs the complete preview URL and identity values at DEBUG. This must be redacted before release. Until it is fixed, do not enable DEBUG logging while processing real preview tokens or customer identity data; use `PersonalizationModule.setLogging('NONE')` in production. Preview is not a non-tracking mode: preview content can carry engagement payloads, so keep it behind the same successful opt-in gate. Use `MockContentZone` for local content that must avoid network decisions and engagement.

### Custom URL scheme

Custom schemes do not authenticate the receiving app and can be claimed by another installed app. Use this example only on controlled development or internal preview devices; use verified links for production preview tokens. The sample uses `yourappscheme` and the URL shape below. Replace both with the exact scheme, host, path, and query contract generated by the authoritative mobile backend procedure; do not assume this illustrative shape is universal.

```
yourappscheme://preview?sfp-preview=TOKEN
```

Register the scheme in iOS `Info.plist`.

```xml
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourappscheme</string>
    </array>
  </dict>
</array>
```

Forward custom-scheme URLs from the existing iOS app delegate.

```swift
override func application(
  _ app: UIApplication,
  open url: URL,
  options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
  return RCTLinkingManager.application(app, open: url, options: options)
}
```

On Android, preserve the existing launcher filter and activity attributes, set the main activity launch mode to `singleTask`, and add the custom-scheme filter.

```xml
<activity
  android:name=".MainActivity"
  android:exported="true"
  android:launchMode="singleTask">

  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
      android:scheme="yourappscheme"
      android:host="preview" />
  </intent-filter>
</activity>
```

Validate scheme, host, path, credentials, and the exact query parameter before passing a URL to native code. Handle both cold-start and foreground URLs.

```tsx
import { useEffect } from "react";
import { Linking } from "react-native";
import { PersonalizationModule } from "@salesforce-personalization/react-native-personalization";

function getTrustedPreviewUrl(rawUrl: string): string | null {
  try {
    const url = new URL(rawUrl);
    const token = url.searchParams.get("sfp-preview");
    const queryKeys = Array.from(url.searchParams.keys());
    const trusted =
      url.protocol === "yourappscheme:" &&
      url.hostname === "preview" &&
      (url.pathname === "" || url.pathname === "/") &&
      url.username === "" &&
      url.password === "" &&
      url.port === "" &&
      url.hash === "" &&
      queryKeys.length === 1 &&
      queryKeys[0] === "sfp-preview" &&
      url.searchParams.getAll("sfp-preview").length === 1 &&
      typeof token === "string" &&
      token.trim() !== "";

    return trusted ? rawUrl : null;
  } catch {
    return null;
  }
}

export function PreviewUrlHandler() {
  useEffect(() => {
    const handleUrl = async (rawUrl: string) => {
      const trustedUrl = getTrustedPreviewUrl(rawUrl);
      if (!trustedUrl) return;
      try {
        await PersonalizationModule.handlePreviewUrl(trustedUrl);
      } catch {
        console.error("Preview URL could not be applied");
      }
    };
    void Linking.getInitialURL()
      .then((url) => {
        if (url) void handleUrl(url);
      })
      .catch(() => console.error("Initial URL could not be read"));
    const subscription = Linking.addEventListener("url", ({ url }) => {
      void handleUrl(url);
    });
    return () => subscription.remove();
  }, []);
  return null;
}
```

Preview receipt updates refetch only the affected zone. A mounted zone can also refetch through its controller or when its name changes. `PersonalizationModule.isPreview(name)` reads the current state for that zone.

### Universal Links and Android App Links

HTTPS links are a separate integration, not a replacement scheme string in the custom-scheme examples. Before accepting HTTPS preview URLs, complete all of the following platform verification work and change the parser allowlist to the exact HTTPS host and path issued by your organization.

For iOS Universal Links:

- Host an `apple-app-site-association` file on the trusted HTTPS domain.
- Add the Associated Domains capability with the matching applinks domain.
- Restrict the association file to the exact preview path.
- Forward `NSUserActivityTypeBrowsingWeb` from the app delegate to `RCTLinkingManager.application(_:continue:restorationHandler:)`.
- Test installation and link association on a physical device.

For Android App Links:

- Host `assetlinks.json` with the production application ID and signing certificate.
- Add an HTTPS intent filter with exact scheme, host, and path constraints.
- Set `android:autoVerify="true"` on that filter.
- Verify association status for the installed release-signed app.
- Test cold-start and foreground delivery on a physical device.

Do not claim Universal Link or App Link support until these domain-controlled files, native forwarding methods, release signing identities, and path rules have been validated together.

## Design-Time Rendering

`MockContentZone` renders local data without a network decision and never sends engagement because mock context has no engagement payloads.

Keep both `allowedComponents` and `mockContent` identities stable. In the reviewed source, changing either identity retriggers the effect. Recreating either inline on every render re-runs the mock fetch each render - an unnecessary-refetch footgun from missing memoization. It is not a self-sustaining loop: the effect only updates the zone's own state and never feeds those prop identities back. Use module-level constants or useMemo so the fetch runs only when the fixture actually changes.

```tsx
import {
  MockContentZone,
  SalesforceBanner,
} from "@salesforce-personalization/react-native-personalization";

const mockBannerComponents = [SalesforceBanner()];

const provideMockBanner = () => ({
  componentName: "Salesforce_Banner",
  header: "Welcome!",
  imageUrl: "https://images.example.com/banner.jpg",
});

export function BannerPreview() {
  return (
    <MockContentZone
      name="HomeScreen"
      allowedComponents={mockBannerComponents}
      mockContent={provideMockBanner}
    />
  );
}
```

If mock data or handlers depend on component props, create stable identities once for the mounted preview and remount intentionally when the fixture changes. Do not silence the loop by setting the simulated delay to zero.

## Identity and Events

Set identity after consent and before mounting the zone that needs it. Identity changes affect later requests but do not refresh an already mounted zone. Attribute values must be strings, and `setAttributes` requires a nonempty object.

```tsx
import { PersonalizationModule } from "@salesforce-personalization/react-native-personalization";

export async function applySignedInIdentity(): Promise<void> {
  await PersonalizationModule.setProfileId("user-123");
  await PersonalizationModule.setAttributes({ tier: "gold", age: String(30) });
}
```

Handle rejection at the app's identity boundary. After all identity mutations succeed, refresh that zone's dedicated controller once; for an account switch, unmount live zones, complete the identity transition, then remount them. `clearAllAttributes()` does not clear the profile ID or party-identification fields, and this plugin version exposes no public API to clear them. Do not set those identifiers in an app that must remove identity on logout until the compatible release documents a supported native identity-reset operation.

Track application events through the same public module from a named async function. Handle rejection at the app's event boundary.

```tsx
import { PersonalizationModule } from "@salesforce-personalization/react-native-personalization";

export async function trackProductView(productId: string): Promise<void> {
  try {
    await PersonalizationModule.track({
      objType: "CustomEvent",
      name: "product_viewed",
      attributes: { productId },
    });
  } catch {
    console.error("Product view could not be tracked");
  }
}
```

The event union also supports engagement, system, cart, order, and catalog events. Use the event shape exported by the installed compatible release.

**note:** **Prepare Salesforce (backend prerequisite):** A Salesforce administrator must configure the mobile personalization resources before the app can receive content: create a mobile content zone for each placement, match the app's content-zone name exactly (spelling and case), assign every experience template the zone is allowed to serve (`Salesforce_Banner`, `Salesforce_Recommendations`, or your cloned/custom names), supply required fields, configure View and Click engagement payloads, activate the configuration, and verify a test decision for each zone. See [Set Up Mobile Content Zones](https://help.salesforce.com/s/articleView?id=mktg.persnl_experience_mobile_content_zones_register.htm). Do not substitute the web sitemap content-zone procedure for the mobile procedure.

<!-- document id=05026f4848f0b734a4b70ab52ae58e47e8346500c49191b279fce09638451c86 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/decisioning-api/decisioning-api-request-personalization.md -->

# Request Personalization

Request personalized content for data derived from Salesforce Data 360.

## Method and Endpoint

`POST /personalization/decisions`

## Aliased Endpoints

- `/personalization/v1/decisions`

## Request Example

**note:** To request personalized content for an Account, replace `"individualId": ""` with `"profileId": ""`. You can also pass `individualId` as part of the `profileId` attribute.

```curl
curl "/personalization/decisions" \
  -X POST \
  -H "content-type: application/json" \
  -d '{
  "context": {
    "individualId": "",
    "unifiedIndividualId": "",
    "dataspace": "",
    "anchorId": "",
    "anchorType": "",
    "correlationId": "",
    "messageId": "",
    "requestUrl": "",
    "customContextVariable": ""
  },
  "personalizationPoints": [
    {
      "id": "",
      "name": "",
      "decisionId": ""
    }
  ],
  "profile": {},
  "executionFlags": [
    "TestMode"
  ]
}'
```

## Body

**note:** To request personalized content for an Account, replace `"individualId": ""` with `"profileId": ""`. You can also pass `individualId` as part of the `profileId` attribute.

**Media type**: `application/json`

```json
{
  "context": {
    "individualId": "",
    "unifiedIndividualId": "",
    "dataspace": "",
    "anchorId": "",
    "anchorType": "",
    "correlationId": "",
    "messageId": "",
    "requestUrl": "",
    "customContextVariable": ""
  },
  "personalizationPoints": [
    {
      "id": "",
      "name": "",
      "decisionId": ""
    }
  ],
  "profile": {},
  "executionFlags": ["TestMode"]
}
```

| Parameter                          | Type             | Description                                                                                                                                                                                                                                                                                                                |
| ---------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`                          | Object           | Details that define the circumstances surrounding a personalization request when it occurs. Personalization records the context provided as an extension of Personalization Record in the Personalization Record Data Lake Object (DLO) for this request.                                                                  |
| `personalizationPoints`            | Array            | Details of the personalization points used in this request. Make sure all personalization points use the same profile data graph.                                                                                                                                                                                          |
| `personalizationPoints.id`         | String           | The core ID of a personalization point. Optional if name is provided.                                                                                                                                                                                                                                                      |
| `personalizationPoints.name`       | String           | The API name of a personalization point. Optional if id is provided.                                                                                                                                                                                                                                                       |
| `personalizationPoints.decisionId` | String           | Optional ID of the specific decision that must be returned without rule evaluation (for testing purpose)                                                                                                                                                                                                                   |
| `profile`                          | Object           | A Data 360 Hot Layer Profile. If a profile is provided, the API always uses this profile and skips retrieving the profile from Data 360.                                                                                                                                                                                    |
| `executionFlags`                   | Array of Strings | Enumerated values: <ul><li>`TestMode`: Indicates whether the call is operating in test mode. In this mode, no outputs are recorded to the data lake.</li><li>`ContextOnly`: Indicates that a call must not look up a profile.</li><li>`EnableDiagnostics`: Indicates that the response must include diagnostics.</li></ul> |

## Responses

### 200

#### Example response

```json
{
  "personalizations": [
    {
      "personalizationId": "",
      "personalizationPointId": "",
      "personalizationPointName": "",
      "data": [
        {
          "personalizationContentId": ""
        }
      ],
      "attributes": {},
      "diagnostics": [
        {
          "code": "",
          "description": ""
        }
      ]
    }
  ],
  "diagnostics": [
    {
      "code": "",
      "description": ""
    }
  ],
  "requestId": ""
}
```

### Response Body

**Media type**: `application/json`

| Parameter                                   | Type   | Description                                                                                                                                    |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `personalizations`                          | Array  | Details of the personalization content matching the expected schema of the Personalization Point, and diagnostics.                             |
| `personalizations.personalizationId`        | String | The response ID.                                                                                                                               |
| `personalizations.personalizationPointId`   | String | The core identifier for the personalization point used in this request.                                                                        |
| `personalizations.personalizationPointName` | String | The API name identifier for the personalization point used in this request. This identifier is a reflection of what was passed in the request. |
| `personalizations.data`                     | Array  | An array of content objects matching the expected schema of the Personalization Point.                                                         |
| `personalizations.attributes`               | Object | Personalization Attribute values by Attribute Developer Name.                                                                                  |
| `personalizations.diagnostics`              | Array  | Diagnostic information on errors. Available only for authenticated requests.                                                                   |
| `diagnostics`                               | Array  | Diagnostic information on errors. Available only for authenticated requests.                                                                   |
| `diagnostics.code`                          | String | The error code. Available only for authenticated requests.                                                                                     |
| `diagnostics.description`                   | String | The detailed message describing the error. Available only for authenticated requests.                                                          |
| `requestId`                                 | String | Unique identifier for this request and response.                                                                                               |

## Types

### context

Details regarding the context from which the request is taking place. Schema to match, or be an extension of, a Personalization Record. Personalization records the context provided as an extension of Personalization Record in the Personalization Record Data Lake Object (DLO) for this request.

| Parameter               | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `individualId`          | String | The individual ID to be associated with a Data 360 Profile.                                                                                                                                                                                                                                                                                                                                    |
| `profileId`             | String | The individual or account ID to be associated with a Data 360 profile.                                                                                                                                                                                                                                                                                                                        |
| `unifiedIndividualId`   | String | Optional Unified Individual ID to be associated with a Data 360 Profile. This ID isn't used for profile lookup. It's only used to enable accurate experimentation partitioning in cases that don’t require a profile lookup.                                                                                                                                                                  |
| `dataspace`             | String | The data space that defines the boundary of a personalization context.                                                                                                                                                                                                                                                                                                                        |
| `anchorId`              | String | The anchor ID to be used by Personalizers referencing a DMO that the end user is interacting with.                                                                                                                                                                                                                                                                                            |
| `anchorType`            | String | The anchor type to be used by Personalizers.                                                                                                                                                                                                                                                                                                                                                  |
| `correlationId`         | String | Optional ID used for attribution involving multiple personalization requests where a future engagement can contain this ID and is attributed to more than one personalization.                                                                                                                                                                                                                |
| `messageId`             | Any    | Optional ID representing an individual outbound message.                                                                                                                                                                                                                                                                                                                                      |
| `requestUrl`            | String | Optional URL used to automatically parse data such as UTM parameters.                                                                                                                                                                                                                                                                                                                         |
| `customContextVariable` | String | The custom context value that the recommendation filters refer to filter items. This data isn't recorded in Data 360. For information about configuring recommendation filters to use custom context variables, see [Filter Recommendations Using Dynamic Context Variables](https://help.salesforce.com/s/articleView?id=mktg.persnl_recommender_filter_using_dynamic_variable.htm&type=5) |

### personalization

| Parameter                       | Type   | Description                                                                                                                                   |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `personalizationId`             | String | The ID of the response.                                                                                                                       |
| `personalizationPointId`        | String | The core identifier for the personalization point used in the request.                                                                        |
| `personalizationPointName`      | String | The API name identifier for the personalization point used in the request. This identifier is a reflection of what was passed in the request. |
| `data`                          | Array  | An array of Content Objects matching the expected schema of the Personalization Point.                                                        |
| `data.personalizationContentId` | String | The identifier for a Personalization Content Record.                                                                                          |
| `attributes`                    | Object | Personalization Attribute values by Attribute Developer Name.                                                                                 |
| `diagnostics`                   | Array  | Diagnostic information on errors.                                                                                                             |
| `diagnostics.code`              | String | The error code                                                                                                                                |
| `diagnostics.description`       | String | The detailed message describing the error.                                                                                                    |

### personalizationPoint

| Parameter    | Type   | Description                                                                                               |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------- |
| `id`         | String | The core ID of a personalization point. Optional if name is provided.                                     |
| `name`       | String | The API name of a personalization point. Optional if id is provided.                                      |
| `decisionId` | String | Optional ID of the specific decision that must be returned without rule evaluation (for testing purpose). |

### personalizationRequest

A request for one or more personalizations to be made for an individual. If values conflict due to duplicate keys within `context`, `events`, and `profile`, `context` takes precedence.

| Parameter                          | Type             | Description                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`                          | Object           | Required. Details regarding the context from which the request is taking place. Schema to match, or be an extension of, a Personalization Record. Context provided as an extension of Personalization Record is recorded in the Personalization Record Data Lake Object (DLO) for this request.                             |
| `personalizationPoints`            | Array            | Required                                                                                                                                                                                                                                                                                                                    |
| `personalizationPoints.id`         | String           | The core ID of a personalization point. Optional if name is provided.                                                                                                                                                                                                                                                       |
| `personalizationPoints.name`       | String           | The API name of a personalization point. Optional if id is provided.                                                                                                                                                                                                                                                        |
| `personalizationPoints.decisionId` | String           | Optional ID of the specific decision that must be returned without rule evaluation (for testing purpose).                                                                                                                                                                                                                   |
| `profile`                          | Object           | A Data 360 Hot Layer Profile. If a profile is provided, the API always uses this profile and skips retrieving the profile from Data 360.                                                                                                                                                                                     |
| `executionFlags`                   | Array of Strings | Enumerated values: <ul><li>`TestMode`: Indicates whether the call is operating in test mode. In this mode, no outputs are recorded to the data lake.</li><li>`ContextOnly`: Indicates that a call must not look up a profile.</li><li>`EnableDiagnostics`: Indicates that the response must include diagnostics.'</li></ul> |

### personalizationResponse

| Parameter                                   | Type   | Description                                                                                                                                    |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `personalizations`                          | Array  |                                                                                                                                                |
| `personalizations.personalizationId`        | String | The ID of the response.                                                                                                                        |
| `personalizations.personalizationPointId`   | String | The core identifier for the personalization point used in this request.                                                                        |
| `personalizations.personalizationPointName` | String | The API name identifier for the personalization point used in this request. This identifier is a reflection of what was passed in the request. |
| `personalizations.data`                     | Array  | An array of Content Objects matching the expected schema of the Personalization Point.                                                         |
| `personalizations.attributes`               | Object | Personalization Attribute values by Attribute Developer Name.                                                                                  |
| `personalizations.diagnostics`              | Array  | Diagnostic information on errors                                                                                                               |
| `diagnostics`                               | Array  | Diagnostic information on errors                                                                                                               |
| `diagnostics.code`                          | String | The error code                                                                                                                                 |
| `diagnostics.description`                   | String | The detailed message describing the error                                                                                                      |
| `requestId`                                 | String | Unique identifier for this request and response.                                                                                               |

<!-- document id=d1601965181045d98a9e35a9231fbcf1a3e149441290f1d6dc8d77ed84f1611f url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/web-integration/request-personalization-through-sitemap.md -->

# Request Personalization Through the Sitemap

The Personalization property of the `SalesforceInteractions` object enables you to interact with the Decisioning API and request for one or more personalizations for personalization points on your Sitemap.

To fetch personalized data, call the `fetch` method on the `Personalization` property. The `fetch` method accepts an array of personalization point names as parameters.

If you have more than one data space, you must define a data space you'd like to use in the `fetch` method within the `SalesforceInteractions.init` function, as shown in the following example. If you don't define a data space, the `fetch` method uses the `default` dataspace.

```javascript
SalesforceInteractions.init({
  consents: [],
  personalization: {
    dataspace: "personalizationDemo",
  },
});
```

In the following example, we request personalizations for the `home_hero` and `home_recommendations` personalization points.

```javascript
SalesforceInteractions.Personalization.fetch(["home_recommendations", "home_hero"]).then(
  (personalizationResponse) => {
    // Custom logic to render personalization on the website
    console.log("Personalization Response", personalizationResponse);
  },
);
```

The `fetch` method returns a Promise. After the Promise is resolved, the arrow function `(personalizationResponse) => { ... }` is executed. Within the arrow function, you can implement your own custom logic to render the fetched personalized data on your website. In the preceding example, the code simply logs the `personalizationResponse` object to the console using `console.log()`.

The `personalizationResponse` object in the preceding example represents the response received from the Decisioning API. For successful personalizations, the response object contains personalized data for the personalization points specified in the request.

The following is an example of personalized data received from the Decisioning API.

```json
"personalizations": [
   {
      "personalizationId": "96c4a971-71f5-4779-a82d-2c72dfa964fe",
      "requestId": "c73e348d-3336-4ed4-90f5-c3ed63280e10",
      "individualId": "ba8f56683e2ca01c",
      "dataSpace": "default",
      "personalizationPointId": "9ppSG00000004I9YAI",
      "personalizationPointName": "home_recommendations",
      "dmoName": "ssot__GoodsProduct__dlm",
      "data": [
            {
               "ssot__IsSellable__c": "Y",
               "ssot__AgeId__c": "",
               "KQ_PrimaryProductCategory__c": " ",
               "ssot__BrandId__c": "NTO",
               "ssot__Id__c": "6010042",
               "ssot__DataSourceId__c": "nto_product_data",
               "KQ_Id__c": " ",
               "ImageUrl__c": "https://www.northerntrailoutfitters.com/dw/image/v2/BDPX_PRD/on/demandware.static/-/Sites-nto-alpine-nutrition/default/dwf19b5e9c/images/hi-res/go-brew.jpg",
               "ssot__ColorId__c": "",
               "ssot__FabricId__c": "",
               "personalizationContentId": "96c4a971-71f5-4779-a82d-2c72dfa964fe:0",
               "PurchaseUrl__c": "https://www.northerntrailoutfitters.com/default/gobrew-connected-coffee-machine-6010042.html",
               "ssot__PrimaryProductCategory__c": "Coffee Machines",
               "ssot__Name__c": "GoBrew Connected Coffee Machine",
               "ssot__GenderId__c": "",
               "ssot__ProductSKU__c": "6010042",
               "GoodsProductSales__cio": "[{TotalSoldUnits__c=43.0, ProductId__c=6010042}]"
            }
      ]
   }
]
```

<!-- document id=7831da2af3ee3504878fb4e7e75b525574c1064ba6fe98211c4dc56ef34c862a url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/overview.md -->

# Salesforce Personalization

Personalization is a Customer 360 application that works with Data Cloud to provide personalized experiences across Salesforce clouds. It uses product recommendations and goal-based and rule-based content targeting to deliver personalized recommendations or custom content to users.

## How Personalization Works

Personalization uses Data Cloud to isolate, organize, and prepare data for use as personalized content. Data Cloud data spaces provide logical partitions to organize the data for profile unification, calculated insights, and marketing.

A data space contains data graphs that use data model objects (DMOs) to build precalculated views of your data. Personalization uses these data graphs to more quickly and efficiently obtain and deliver personalized content to users or site visitors. Personalization uses its own DMOs when making decisions about which individuals are eligible to receive a personalization, and when determining what personalized content to provide.

Personalization is delivered in the following ways.

- A Customer 360 Personalization application that centralizes connected and personalized experiences across clouds.
- Personalization as a Service, providing real-time, Data Cloud-based, personalization functionality to Salesforce customers across channels.

![How Personalization Works](https://developer.salesforce.com/docs/media/persnl_basics_overview_works.png)

## Data Cloud and Personalization

To generate and present unique, personalized content experiences, Personalization uses Data Cloud profile and item data graphs, calculated insights, segments, and real-time behavioral data.

![Image showing the Data Cloud real-time high level data flow.](https://developer.salesforce.com/docs/media/einstein-personalization-data-cloud.png)

1. User interaction data is ingested using Salesforce Interactions SDK. Data is simultaneously ingested into two processing layers - the real-time layer for immediate processing, and the standard data layer for regular processing along with other ingested data.
2. Data Cloud identity resolution performs real-time matching to identify a user profile. If the user is unknown, a new profile is created.
3. The known or anonymous profile in the real-time data graph is updated with ingested engagement and profile event data.
4. Real-time insights and segments are calculated. The real-time profile data graph is updated with metrics and segmentation results.
5. When a personalization decision is required, Personalization.. calls the Data Cloud profile API to obtain the updated individual profile from the real-time profile data graph.

## See Also

- [_Salesforce Help_: Personalization](https://help.salesforce.com/s/articleView?id=mktg.persnl_basics.htm)
- [_Salesforce Help_: Personalization and Data Cloud Setup](https://help.salesforce.com/s/articleView?id=mktg.persnl_setup.htm)
- [_Salesforce Help_: About Salesforce Data Cloud](https://help.salesforce.com/s/articleView?id=sf.c360_a_data_cloud.htm)
- [_Salesforce Help_: Manage Data Spaces](https://help.salesforce.com/s/articleView?id=sf.c360_a_data_spaces.htm)
- [_Salesforce Help_: Data Graphs](https://help.salesforce.com/s/articleView?id=sf.c360_a_data_graphs.htm)
- [_Salesforce Help_: Create and Activate Segments](https://help.salesforce.com/s/articleView?id=sf.c360_a_segments.htm)
- [_Salesforce Help_: Enhance Data with Insights](https://help.salesforce.com/s/articleView?id=sf.c360_a_insights.htm)

<!-- document id=7e03d8230866e3b0a4dd56c2c4b87a169992e1d6bbb12b68591a2acc64f43c3a url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/sample-templates/batch-persnl-sample-templates.md -->

# Sample AMPscript Templates for Batch Personalization

After activating batch personalization decision data to Marketing Cloud Engagement (MCE), you can use AMPscript to pull decision data into MCE messages. For information about how to use AMPscript in MCE, see [AMPscript for Marketing Cloud Engagement](https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/guide).

The data included in a batch personalization output depends on the response template linked to the personalization point that’s evaluated in a batch personalization.

You can extend the sample templates provided here to suit your data configuration. However, keep in mind that the API names of the item attributes differ depending on your data space or the naming convention if they're custom fields.

## Sample AMPscript Template for Article Recommendations

The sample template is curated based on a personalization point with these configuration.

| SAMPLE CONFIGURATION             |                                                                             |
| -------------------------------- | :-------------------------------------------------------------------------- |
| Type                             | Recommendations                                                             |
| Object being recommended         | Knowledge Article Version                                                   |
| Items returned                   | 4                                                                           |
| Response template configuration: |                                                                             |
| Personalization attributes       | Recs_Header                                                                 |
| Item attributes                  | ssot\_\_Id\_\_c ssot\_\_Name\_\_c ssot\_\_ExternalURL\_\_c ssot\_\_URL\_\_c |

```text
%%[
    /* Get JSON data from the Sendable Data Extension */

    SET @data = AttributeValue("ActivationData")

    /* Get a list of personalization attributes */

    SET @attrRows = BuildRowsetFromJSON(@data, "$.['attributes'][*]", true)

    /* Get a list of recommended items */

    SET @recRows = BuildRowsetFromJSON(@data, "$.['data'][*]", true)

    /* Get a value of a "Recs_Header" personalization attribute */

    FOR @i = 1 TO RowCount(@attrRows) DO
        IF Field(Row(@attrRows, @i), "name") == "Recs_Header" THEN
            SET @RECS_HEADER = Field(Row(@attrRows, @i), "value")
        ENDIF
    NEXT @i
]%%

<div style="max-height: 100%; max-width: 600px; position: relative; overflow: hidden; margin: 20px auto; text-align: center;">
    <div style="display: table; width: 100%; max-height: 100%;">

    <h1>%%=V(@RECS_HEADER)=%%</h1>

    %%[

    /* Loop through each recommended item, extract its details and render HTML */

    FOR @i = 1 TO RowCount(@recRows) DO
        SET @ID = Field(Row(@recRows, @i), "ssot__Id__c")
        SET @IMAGE = Field(Row(@recRows, @i), "ssot__ExternalURL__c")
        SET @NAME = Field(Row(@recRows, @i), "ssot__Name__c")
        SET @URL = Field(Row(@recRows, @i), "ssot__URL__c")
    ]%%

    <span style="display: inline-block; margin-top: 10px;">
        <a href="%%=RedirectTo(@URL)=%%" style="display: block; width: 300px; overflow: hidden;">
            <img src="%%=V(@IMAGE)=%%" style="border: 0; width: 90%; margin: 10px;">
        </a>
        <div style="padding: 0px; margin: 0px; width: 300px; overflow: hidden;">
            <h3 style="padding: 0px; margin: 10px; font-size: 16px; line-height: 20px; height: 40px; overflow: hidden;">
                %%=V(@NAME)=%%
            </h3>
        </div>
    </span>

    %%[ NEXT @i ]%%

    </div>
</div>
```

## Sample AMPscript Template for Product Recommendations

The sample template is curated based on a personalization point with these configuration.

| SAMPLE CONFIGURATION             |                                                                                                                                                                                                                                                                                    |
| -------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Type                             | Recommendations                                                                                                                                                                                                                                                                    |
| Object being recommended         | Goods Product                                                                                                                                                                                                                                                                      |
| Items returned                   | 4                                                                                                                                                                                                                                                                                  |
| Response template configuration: |                                                                                                                                                                                                                                                                                    |
| Personalization attributes       | Recs_Header                                                                                                                                                                                                                                                                        |
| Item attributes                  | ssot\_\_Id\_\_c ssot\_\_Name\_\_c ImageURL\_\_c URL\_\_c UnitPrice\_\_c **Note**: The attributes without the `ssot` prefix are custom attributes added to the Goods Product DMO. With proper mapping, you can add custom fields to any DMO and include them in decision responses. |

```text
%%[
    /* Get JSON data from the Sendable Data Extension */

    SET @data = AttributeValue("ActivationData")

    /* Get a list of personalization attributes */

    SET @attrRows = BuildRowsetFromJSON(@data, "$.['attributes'][*]", true)

    /* Get a list of recommended items */

    SET @recRows = BuildRowsetFromJSON(@data, "$.['data'][*]", true)

    /* Get a value of a "Recs_Header" personalization attribute */

    FOR @i = 1 TO RowCount(@attrRows) DO
        IF Field(Row(@attrRows, @i), "name") == "Recs_Header" THEN
            SET @RECS_HEADER = Field(Row(@attrRows, @i), "value")
        ENDIF
    NEXT @i
]%%

<div style="max-height: 100%; max-width: 600px; position: relative; overflow: hidden; margin: 20px auto; text-align: center;">
    <div style="display: table; width: 100%; max-height: 100%;">

    <h1>%%=V(@RECS_HEADER)=%%</h1>

    %%[

    /* Loop through each recommended item, extract its details and render HTML */

    FOR @i = 1 TO RowCount(@recRows) DO
        SET @IMAGE = Field(Row(@recRows, @i), "ImageUrl__c")
        SET @NAME = Field(Row(@recRows, @i), "ssot__Name__c")
        SET @PRICE = Field(Row(@recRows, @i), "UnitPrice__c")
        SET @URL = Field(Row(@recRows, @i), "URL__c")
    ]%%

    <span style="display: inline-block; margin-top: 10px;">
        <a href="%%=RedirectTo(@URL)=%%" style="display: block; width: 300px; overflow: hidden;">
            <img src="%%=V(@IMAGE)=%%" style="border: 0; width: 90%; margin: 10px;">
        </a>
        <div style="padding: 0px; margin: 0px; width: 300px; overflow: hidden;">
            <h3 style="padding: 0px; margin: 10px; font-size: 16px; line-height: 20px; height: 40px; overflow: hidden;">
                %%=V(@NAME)=%%
            </h3>
            <p style="padding: 0px; margin: 10px; font-size: 14px;">
                Price: %%=FormatCurrency(@PRICE, "en-US")=%%
            </p>
        </div>
    </span>

    %%[ NEXT @i ]%%

    </div>
</div>
```

<!-- document id=a8ee5394502ee636e90e85734215e0c988d639d64d5a35e99160e51e84790ecf url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/sample-templates/sample-templates.md -->

# Sample Templates

Use these sample templates as reference when using personalization decisions in other systems, like MCE. You can extend and modify these sample templates to suit your requirements.

<!-- document id=a2bcf36bc9aad8b44720fe1e1408ce717c1ba1e613a796a28465f32adc660994 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/experimentation-assignment-api/experimentation-api-authenticated-request.md -->

# Send an Authenticated Experimentation Assignment Request

Place authenticated requests for experiment cohort assignments based on data derived from Salesforce Data 360 through an authenticated endpoint.

## Method and Endpoint

`POST /experimentation/v1/authenticated/assignment`

## Authentication

To authenticate your request, provide a Data 360 access token in the header. For instructions on generating an access token, see [_Data 360 Developer Guide_: Quick Start](https://developer.salesforce.com/docs/data/data-cloud-dev/guide/dc-quick-start.html).

## Request Example

```
curl "/experimentation/v1/authenticated/assignment" \
  -X POST \
  -H "Authorization: Bearer YOUR_DATA_CLOUD_ACCESS_TOKEN"
  -H "content-type: application/json" \
  -d '{
  "context": {
    "individualId": "",
    "dataspace": ""
  },
  "experiments": [
	"experimentIdOrName1", "experimentIdOrName2"
  ],
  "experimentsOverride":[
   { "experiment":"experimentIdNotAttached",
     "cohordId":"cohort_1"}
  ],
   
  "executionFlags": [
    "TestMode","IncludeUnstartedExperiment"
  ]
}'
```

## Body

**Media type**: `application/json`

```json
{
  "context": {
    "individualId": "",
    "dataspace": ""
  },
  "experiments": [
	"experimentIdOrName1", "experimentIdOrName2"
  ],
  "experimentsOverride":[
   { "experiment":"experimentIdNotAttached",
     "cohordId":"cohort_1"}
  ],
  "profile": {},
  "executionFlags": ["TestMode","IncludeUnstartedExperiment"]
}
```

| Parameter        | Type             | Description                                                                                                |
| ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `context`        | Object           | Details regarding the context from which the request is taking place.                                      |
| `experiments`    | Array of Strings | An array of experiment API names or platform IDs in the corresponding dataspace referenced in the context. |
| `experimentsOverride` | String of Object | Optional. Test or preview specific experiment variants by forcing an assignment for a user, bypassing the normal evaluation process. This object requires an `experiment` (ID or API name) and a `cohortId` (the specific variant). This override only functions when the `TestMode` flag is included in `executionFlags`.   |
| `profile`    | Object | Optional. A Data 360 Hot Layer Profile.<ul><li>**Full profile:** The API skips the Data 360 lookup.</li><li>**Partial profile:** The API merges this data with the existing Data 360 profile. If keys match, this request’s value takes priority.</li></ul> |
| `executionFlags` | Array of Strings | Modifiers that change how the request is processed. Supported values:<ul><li>`TestMode`: Evaluate assignments without saving data to the lake.</li><li>`ContextOnly`: Skip the profile lookup.</li><li>`EnableDiagnostics`: Include troubleshooting data in the response.</li><li>`IncludeUnstartedExperiment`: Show experiments that haven't launched (requires authentication).</li></ul>             |

## Responses

### 200

#### Example response

```json
{
  "experiment": "",
  "variableAssignments": [
    {
      "variableId": "",
      "experimentId": "",
      "experimentName": "",
      "data": [],
      "attributes": {}
    }
  ],
  "diagnostics": [
    {
      "code": "",
      "description": ""
    }
  ],
  "requestId": ""
}
```

### Response Body

**Media type**: `application/json`

| Parameter                            | Type   | Description                                                                                                                                                             |
| ------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Response Array`                     | Array  | A list of one or more experiment responses, based on the number of experiment references specified in the request.                                                      |
| `experiment`                         | String | The Platform ID of the Experiment.                                                                                                                                      |
| `variableAssignments`                | Array  | Variable assignments for the experiment. Simple experiments contain one response; multivariate experiments contain nested assignments.                                  |
| `variableAssignments.variableId`     | String | The ID of the assigned cohort. For simple experiments, this matches the `cohortId` in the attributes object that follows.                                               |
| `variableAssignments.experimentId`   | String | The Platform ID of the Experiment.                                                                                                                                      |
| `variableAssignments.experimentName` | String | The API name of the Experiment.                                                                                                                                         |
| `variableAssignments.data`           | String | An optional array of data that can be returned along with the cohort assignment. This is dependent on the response template you chose when designing the experiment.    |
| `variableAssignments.attributes`     | Array  | An array of attributes that can be returned with the cohort assignment. The attributes returned vary depending on the template you chose when designing the experiment. |
| `diagnostics`                        | Array  | Information about errors or warnings encountered during processing.                                                                                                     |
| `diagnostics.code`                   | String | The error code.                                                                                                                                                         |
| `diagnostics.description`            | String | A detailed message describing the error.                                                                                                                                |
| `requestId`                          | String | The unique identifier for the request and response.                                                                                                                     |

## Types

### context

Details regarding the context from which the request is taking place.

| Parameter      | Type   | Description                                                             |
| -------------- | ------ | ----------------------------------------------------------------------- |
| `individualId` | String | The Individual ID associated with a Data 360 Profile.                   |
| `dataspace`    | String | The data space that defines the boundary of an experimentation context. |

### variableAssignment

| Parameter        | Type   | Description                                                                                             |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| `variableId`     | String | The parent cohort ID for multivariate experiments. For simple experiments, this matches the `cohortId`. |
| `experimentId`   | String | The Platform ID of the Experiment.                                                                      |
| `experimentName` | String | The API Name of the Experiment.                                                                         |
| `data`           | String | Optional data returned with the cohort assignment based on the response template.                       |
| `attributes`     | Array  | Attributes returned with the cohort assignment based on the response template.                          |

### experimentAssignmentRequest

A request for one or more experiment assignments for an individual. If values conflict between context, events, and profile, context takes precedence.

| Parameter        | Type             | Description                                                                                                                                          |
| ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`        | Object           | Details regarding the context from which the request is taking place.                                                                                |
| `experiments`    | Array of Strings | Array of experiment API names or platform IDs in the corresponding dataspace referenced in the context.                                              |
| `executionFlags` | Array of Strings | Enumerated values: <ul><li>`TestMode`: Indicates whether the call is operating in test mode. In this mode, no outputs are recorded to the data lake. |

### experimentAssignmentResponse

| Parameter                            | Type   | Description                                                                                                                                                             |
| ------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Response Array`                     | Array  | A list of one or more experiment responses, based on the number of experiment references specified in the request.                                                      |
| `experiment`                         | String | The Platform ID of the Experiment.                                                                                                                                      |
| `variableAssignments`                | Array  | Variable assignments for the experiment. Simple experiments contain one response, and multivariate experiments contain nested assignments.                              |
| `variableAssignments.variableId`     | String | The ID of the assigned cohort. For simple experiments, this matches the `cohortId` in the attributes object that follows.                                               |
| `variableAssignments.experimentId`   | String | The Platform ID of the Experiment.                                                                                                                                      |
| `variableAssignments.experimentName` | String | The API name of the Experiment.                                                                                                                                         |
| `variableAssignments.data`           | String | An optional array of data that can be returned with the cohort assignment. This is dependent on the response template you chose when designing the experiment.          |
| `variableAssignments.attributes`     | Array  | An array of attributes that can be returned with the cohort assignment. The attributes returned vary depending on the template you chose when designing the experiment. |
| `diagnostics`                        | Array  | Information about errors or warnings encountered during processing.                                                                                                     |
| `diagnostics.code`                   | String | The error code.                                                                                                                                                         |
| `diagnostics.description`            | String | A detailed message describing the error.                                                                                                                                |
| `requestId`                          | String | The unique identifier for the request and response.                                                                                                                     |

<!-- document id=15c8e805bfaa755b9a45de284ea6723e0cb6550503d0eea9eed202a52b7a4210 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/decisioning-api/decisioning-api-authenticated-request.md -->

# Send an Authenticated Personalization Request

Place authenticated requests for personalized content for data derived from Salesforce Data Cloud through an authenticated endpoint.

## Method and Endpoint

`POST /personalization/authenticated/decisions`

## Aliased Endpoints

- `/personalization/v1/authenticated/decisions`

## Authentication

You can authenticate your requests by providing a Data Cloud access token in the header of your request. For guidance on how to generate an access token, see the Getting Started section of the [Data Cloud Reference Guide](https://developer.salesforce.com/docs/atlas.en-us.c360a_api.meta/c360a_api/c360a_getting_started_with_cdp.htm).

## Request Example

```curl
curl "/personalization/authenticated/decisions" \
  -X POST \
  -H "Authorization: Bearer YOUR_DATA_CLOUD_ACCESS_TOKEN"
  -H "content-type: application/json" \
  -d '{
  "context": {
    "individualId": "",
    "unifiedIndividualId": "",
    "dataspace": "",
    "anchorId": "",
    "anchorType": "",
    "correlationId": "",
    "messageId": "",
    "requestUrl": ""
  },
  "personalizationPoints": [
    {
      "id": "",
      "name": "",
      "decisionId": ""
    }
  ],
  "profile": {},
  "executionFlags": [
    "TestMode"
  ]
}'
```

## Body

**Media type**: `application/json`

```json
{
  "context": {
    "individualId": "",
    "unifiedIndividualId": "",
    "dataspace": "",
    "anchorId": "",
    "anchorType": "",
    "correlationId": "",
    "messageId": "",
    "requestUrl": ""
  },
  "personalizationPoints": [
    {
      "id": "",
      "name": "",
      "decisionId": ""
    }
  ],
  "profile": {},
  "executionFlags": ["TestMode"]
}
```

| Parameter                          | Type             | Description                                                                                                                                                                                                                                  |
| ---------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`                          | Object           | Details regarding the context from which the request is taking place. Personalization records the context provided as an extension of Personalization Record in the Personalization Record Data Lake Object (DLO) for this request. |
| `personalizationPoints`            | Array            |                                                                                                                                                                                                                                              |
| `personalizationPoints.id`         | String           | The core ID of a personalization point. Optional if name is provided.                                                                                                                                                                        |
| `personalizationPoints.name`       | String           | The API name of a personalization point. Optional if id is provided.                                                                                                                                                                         |
| `personalizationPoints.decisionId` | String           | Optional ID of the specific decision that must be returned without rule evaluation (for testing purpose)                                                                                                                                     |
| `profile`                          | Object           | A Data Cloud Hot Layer Profile. If a profile is provided, the API always uses this profile and skips retrieving the profile from Data Cloud.                                                                                                 |
| `executionFlags`                   | Array of Strings | Enumerated values: <ul><li>`TestMode`: Indicates whether the call is operating in test mode. In this mode, no outputs are recorded to the data lake.</li><li>`ContextOnly`: Indicates that a call must not look up a profile.</ul>           |

## Responses

### 200

#### Example response

```json
{
  "personalizations": [
    {
      "personalizationId": "",
      "personalizationPointId": "",
      "personalizationPointName": "",
      "data": [
        {
          "personalizationContentId": ""
        }
      ],
      "attributes": {},
      "diagnostics": [
        {
          "code": "",
          "description": ""
        }
      ]
    }
  ],
  "diagnostics": [
    {
      "code": "",
      "description": ""
    }
  ],
  "requestId": ""
}
```

### Response Body

**Media type**: `application/json`

| Parameter                                   | Type   | Description                                                                                                                                    |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `personalizations`                          | Array  |                                                                                                                                                |
| `personalizations.personalizationId`        | String | The response ID.                                                                                                                               |
| `personalizations.personalizationPointId`   | String | The core identifier for the personalization point used in this request.                                                                        |
| `personalizations.personalizationPointName` | String | The API name identifier for the personalization point used in this request. This identifier is a reflection of what was passed in the request. |
| `personalizations.data`                     | Array  | An array of content objects matching the expected schema of the Personalization Point.                                                         |
| `personalizations.attributes`               | Object | Personalization Attribute values by Attribute Developer Name.                                                                                  |
| `personalizations.diagnostics`              | Array  | Diagnostic information on errors. Available only for authenticated requests.                                                                   |
| `diagnostics`                               | Array  | Diagnostic information on errors. Available only for authenticated requests.                                                                   |
| `diagnostics.code`                          | String | The error code. Available only for authenticated requests.                                                                                     |
| `diagnostics.description`                   | String | The detailed message describing the error. Available only for authenticated requests.                                                          |
| `requestId`                                 | String | Unique identifier for this request and response.                                                                                               |

## Types

### context

Details regarding the context from which the request is taking place. Schema to match, or be an extension of, a Personalization Record. Personalization records the context provided as an extension of Personalization Record in the Personalization Record Data Lake Object (DLO) for this request.

| Parameter             | Type   | Description                                                                                                                                                                                                                    |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `individualId`        | String | The individual ID to be associated with a Data Cloud Profile.                                                                                                                                                                  |
| `unifiedIndividualId` | String | Optional Unified Individual ID to be associated with a Data Cloud Profile. This ID isn't used for profile lookup. It's only used to enable accurate experimentation partitioning in cases that don’t require a profile lookup. |
| `dataspace`           | String | The data space that defines the boundary of a personalization context.                                                                                                                                                         |
| `anchorId`            | String | The anchor ID to be used by Personalizers referencing a DMO that the end user is interacting with.                                                                                                                             |
| `anchorType`          | String | The anchor type to be used by Personalizers.                                                                                                                                                                                   |
| `correlationId`       | String | Optional ID used for attribution involving multiple personalization requests where a future engagement can contain this ID and is attributed to more than one personalization.                                                 |
| `messageId`           | Any    | Optional ID representing an individual outbound message.                                                                                                                                                                       |
| `requestUrl`          | String | Optional URL used to automatically parse data such as UTM parameters.                                                                                                                                                          |

### personalization

| Parameter                       | Type   | Description                                                                                                                                   |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `personalizationId`             | String | The ID of the response.                                                                                                                       |
| `personalizationPointId`        | String | The core identifier for the personalization point used in the request.                                                                        |
| `personalizationPointName`      | String | The API name identifier for the personalization point used in the request. This identifier is a reflection of what was passed in the request. |
| `data`                          | Array  | An array of Content Objects matching the expected schema of the Personalization Point.                                                        |
| `data.personalizationContentId` | String | The identifier for a Personalization Content Record.                                                                                          |
| `attributes`                    | Object | Personalization Attribute values by Attribute Developer Name.                                                                                 |
| `diagnostics`                   | Array  | Diagnostic information on errors.                                                                                                             |
| `diagnostics.code`              | String | The error code                                                                                                                                |
| `diagnostics.description`       | String | The detailed message describing the error.                                                                                                    |

### personalizationPoint

| Parameter    | Type   | Description                                                                                               |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------- |
| `id`         | String | The core ID of a personalization point. Optional if name is provided.                                     |
| `name`       | String | The API name of a personalization point. Optional if id is provided.                                      |
| `decisionId` | String | Optional ID of the specific decision that must be returned without rule evaluation (for testing purpose). |

### personalizationRequest

A request for one or more personalizations to be made for an individual. If values conflict due to duplicate keys within `context`, `events`, and `profile`, `context` takes precedence.

| Parameter                          | Type             | Description                                                                                                                                                                                                                                                                                     |
| ---------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`                          | Object           | Required. Details regarding the context from which the request is taking place. Schema to match, or be an extension of, a Personalization Record. Context provided as an extension of Personalization Record is recorded in the Personalization Record Data Lake Object (DLO) for this request. |
| `personalizationPoints`            | Array            | Required                                                                                                                                                                                                                                                                                        |
| `personalizationPoints.id`         | String           | The core ID of a personalization point. Optional if name is provided.                                                                                                                                                                                                                           |
| `personalizationPoints.name`       | String           | The API name of a personalization point. Optional if id is provided.                                                                                                                                                                                                                            |
| `personalizationPoints.decisionId` | String           | Optional ID of the specific decision that must be returned without rule evaluation (for testing purpose).                                                                                                                                                                                       |
| `profile`                          | Object           | A Data Cloud Hot Layer Profile. If a profile is provided, the API always uses this profile and skips retrieving the profile from Data Cloud.                                                                                                                                                    |
| `executionFlags`                   | Array of Strings | Enumerated values: <ul><li>`TestMode`: Indicates whether the call is operating in test mode. In this mode, no outputs are recorded to the data lake.</li><li>`ContextOnly`: Indicates that a call must not look up a profile.</li></ul>                                                         |

### personalizationResponse

| Parameter                                   | Type   | Description                                                                                                                                    |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `personalizations`                          | Array  |                                                                                                                                                |
| `personalizations.personalizationId`        | String | The ID of the response.                                                                                                                        |
| `personalizations.personalizationPointId`   | String | The core identifier for the personalization point used in this request.                                                                        |
| `personalizations.personalizationPointName` | String | The API name identifier for the personalization point used in this request. This identifier is a reflection of what was passed in the request. |
| `personalizations.data`                     | Array  | An array of Content Objects matching the expected schema of the Personalization Point.                                                         |
| `personalizations.attributes`               | Object | Personalization Attribute values by Attribute Developer Name.                                                                                  |
| `personalizations.diagnostics`              | Array  | Diagnostic information on errors                                                                                                               |
| `diagnostics`                               | Array  | Diagnostic information on errors                                                                                                               |
| `diagnostics.code`                          | String | The error code                                                                                                                                 |
| `diagnostics.description`                   | String | The detailed message describing the error                                                                                                      |
| `requestId`                                 | String | Unique identifier for this request and response.                                                                                               |

<!-- document id=eb6ce74df726b8ca8adc8776fa831e5d6f1daca1004efd51ebc443728e35f48e url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/web-integration/configure-web-personalization/set-up-content-zones.md -->

# Set Up Content Zones

Use content zones to designate areas on web pages across your website as targets for rendering personalized content from Personalization. You can define content zones in the Interactions SDK Sitemap either globally or for a specific page type. The content zones that you define in the Sitemap are then made available to personalization experience developers via Web Personalization Manager (WPM).

## Content Zone Fields

A content zone contains two fields — a `name` and a `selector`.

| Field Name | Type   | Required | Description                                                                                     |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `name`     | String | Yes      | The name of the content zone. For example, `global_popup` and `product_detail_recommendations`. |
| `selector` | String | No       | The CSS selector of the web page element that the content zone targets.                         |

## Define a Content Zone

You can define content zones in the Interactions SDK Sitemap globally using the `global` configuration. Alternatively, you can define content zones for specific page types using the `pageTypes` configuration.

**Example:** Defining content zones in the `global` configuration of the Sitemap.

```javascript
const config = {
  global: {
    contentZones: [
      { name: "global_popup" },
      { name: "global_infobar" },
      { name: "global_footer", selector: "footer.global-footer" },
    ],
  },
};
```

**Example:** Defining content zones in the pageTypes configuration of the Sitemap.

```javascript
...
pageTypes: [
  {
    name: "home",
    isMatch: () => /^\/$/.test(window.location.pathname),
    interaction: {
      name: "Homepage",
    },
    contentZones: [
      { name: "recommendations_1", selector: "section.product_recs" },
      { name: "recommendations_2", selector: "div#customer-stories" },
    ],
  },
],
...
```

<!-- document id=dc05d5b91e4d691522d3e1ea18eac17e17cccb7fe656e5459dec4575da3dce27 url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/web-integration/configure-web-personalization/set-up-dynamic-context-variables.md -->

# Set Up Dynamic Context Variables

Use dynamic context variables to send user-defined attributes to the Personalization service with every personalization request. These attributes help refine recommendation responses and support advanced filtering logic in your recommenders. Dynamic variables reduce the number of recommenders you need to deliver your use cases. Define context variables in the Interactions SDK Sitemap globally or for specific page types.

## Context Variable Fields

A dynamic context variable contains two fields: a `name` and a `value`.

| Field Name | Type                         | Required | Description                                                                                                                                                                                                  |
| :--------- | :--------------------------- | :------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`     | String                       | Yes      | The name of the contextual attribute. For example, `color`.                                                                                                                                                  |
| `value`    | String, Function, or Promise | Yes      | The value of the contextual attribute. The value can be a static string, a function that returns a string, or a promise that resolves to a string. For example, if the name is `color`, the value is `blue`. |

## Define a Dynamic Context Variable

Define dynamic context variables in the Interactions SDK Sitemap globally in the `global` configuration. Alternatively, define them for specific page types in the `pageTypes` configuration.

### Example: Defining Dynamic Context Variables in the Global Configuration of the Sitemap

```javascript
const sitemapConfig = {
  global: {
    contextualAttributes: {
      loyaltyTier: "GOLD",
      story: SalesforceInteractions.resolvers.fromSelector("#stories"),
    },
  }, // ...The rest of your sitemap configuration
};
```

### Example: Defining Dynamic Context Variables in the `pageTypes` Configuration of the Sitemap

```javascript
...
pageTypes: [
  {
    name: "Product",
    isMatch: () => window.location.pathname.includes("/product/"),
    contextualAttributes: {
      categoryAttribute: "Footwear",
      colorAttribute: SalesforceInteractions.cashDom('.btn.btn-primary.btn-lg').text()
    }
  }
],
...
```

Dynamic context variables work with string, number, and date filter fields. Use dynamic context variables with single-value operators, the **Between** operator (minimum and maximum values), and date-specific operators such as **Last/Next Number of Days** and **Last/Next Number of Minutes**.

To learn more about advanced filtering with dynamic context variables, see [Filter Recommendations Using Dynamic Context Variables](https://help.salesforce.com/s/articleView?id=mktg.persnl_recommender_filter_using_dynamic_variable.htm).

## Reserved Contextual Attributes

The Interactions SDK automatically sends a set of standard contextual attributes with every personalization request. You can override some of these attributes in your sitemap configuration, but if the SDK has a valid value for an attribute, it overwrites your custom value. Before overriding a reserved attribute, verify that your custom value takes precedence in your implementation and that it doesn't interfere with expected personalization results.

| Attribute                  | Description                                                                                                                                                                                                                                                              | Value override allowed? | Channel     |
| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------- | :---------- |
| `dataspace`                | The dataspace for the personalization request.                                                                                                                                                                                                                           | No                      | Web, Mobile |
| `anchorId`                 | The identifier of the anchor item (for example, a product or content item) on the current page.                                                                                                                                                                          | Yes                     | Web, Mobile |
| `anchorType`               | The Data Model Object name associated with the anchor item.                                                                                                                                                                                                              | Yes                     | Web, Mobile |
| `individualId`             | Unique identifier of the website visitor, generated by the SDK. This typically corresponds to a device ID.                                                                                                                                                               | No                      | Web         |
| `channel`                  | The channel from which the request originates, determined by the SDK in use. The SDK sends a fixed value of 'Web' or 'Mobile'. For example, `Web`, `Mobile`, `Flow`, `Email`, `SMS`, `WhatsApp`, `POS`, `ATM`, `Service Cloud`, `Sales Cloud`, `Agent`, `Server`, `OTT`. | No                      | Web, Mobile |
| `channelContext`           | The hostname for web, or the mobile app identifier for mobile. For example, `salesforce.com`.                                                                                                                                                                            | No                      | Web, Mobile |
| `locale`                   | The locale used to filter and rank recommendations for multi-locale deployments. This value is not set automatically by the SDK. For example, `en_US`.                                                                                                                   | Yes                     | Web, Mobile |
| `requestUrl`               | The URL from which the personalization request was made. For example, `https://commercecloud.salesforce.com/s/nto/default/home`.                                                                                                                                         | No                      | Web         |
| `pageType`                 | The page type from the sitemap where the personalization request originated. For example, `Product`.                                                                                                                                                                     | Yes                     | Web         |
| `interaction`              | The interaction name from the page type where the personalization request originated.                                                                                                                                                                                    | Yes                     | Web         |
| `p13n_sys_requestTimeZone` | The browser's time zone. For example, `Europe/Vienna`.                                                                                                                                                                                                                   | No                      | Web         |
| `utm_source`               | UTM source parameter captured from the page URL.                                                                                                                                                                                                                         | No                      | Web         |
| `utm_campaign`             | UTM campaign parameter captured from the page URL.                                                                                                                                                                                                                       | No                      | Web         |
| `utm_medium`               | UTM medium parameter captured from the page URL.                                                                                                                                                                                                                         | No                      | Web         |
| `utm_content`              | UTM content parameter captured from the page URL.                                                                                                                                                                                                                        | No                      | Web         |
| `utm_term`                 | UTM term parameter captured from the page URL.                                                                                                                                                                                                                           | No                      | Web         |

<!-- document id=ee199e025a6208ed601b3129484b5ec5efe0d9442c8ba7af34504f744fe3e0aa url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/web-integration/track-personalization-engagement.md -->

# Track Personalization Engagement

To power Personalization's advanced machine learning, it's essential to capture and analyze how users interact with your site, especially with personalized content. This continuous data collection helps Personalization better understand user behavior, allowing the system to deliver recommendations that become more accurate and hyper-personalized over time.

User interaction event logs are automatically sent from the Web SDK sitemap to Data Cloud for tracking. This data is crucial for powering machine learning algorithms and for reporting and analytics within Data Cloud. The Data Cloud module processes these structured events by flattening them, assigning an `eventType` for categorization, and organizing them into data streams. You can even merge multiple event types into a single data stream.

To ensure events are categorized correctly, you must update your Data Cloud Web Schema. The schema defines the structure for event types, including their available fields, required fields, and field names. For more information on the structure of the Data Cloud Web Schema, see [Mobile and Web SDK Schema Quick Guide for Data Cloud](https://developer.salesforce.com/docs/data/data-cloud-int/guide/c360-a-mobile-web-sdk-schema-quick-guide.html).

## Engagement Destinations

An Engagement Destination is a configuration that determines how user interaction events are processed, categorized, and sent to Data Cloud for analysis. When you configure a personalization experience in the Web Personalization Manager, you can choose a standard, out-of-the-box (OOTB) destination or create a custom one to fit your needs.

For more information on configuring a personalization experience and setting an engagement destination, see [Creating a Personalization Experience](https://help.salesforce.com/s/articleView?id=mktg.persnl_wpm_create_personalization_experiences.htm).

## Out-of-the-Box Engagement Destinations

Personalization provides two OOTB destinations for common use cases: Product Engagement and Website Engagement. These destinations use predefined event types to map engagement data to the correct Data Model Objects (DMOs).

| Engagement Destination | Associated Event Type | Recommended DMO           |
| :--------------------- | :-------------------- | :------------------------ |
| Product Engagement     | `catalog`             | Product Browse Engagement |
| Website Engagement     | `userEngagement`      | Website Engagement        |

### Product Engagement

- Use this destination exclusively for personalization experiences that are based on recommendations.
- The event payload always uses the `catalog` event type.
- The SDK automatically sends specific interaction names: `catalog-object-view-start` for views and `catalog-object-click` for clicks.
- The event always includes an `id` field, that contains the unique identifier of the recommended item from your catalog, and a `type` field, which has a static value of `Product`.

Here's an example payload for a Product Engagement sent to Data Cloud.

```json
{
  "id": "a00Ws000004x7vcIAA",
  "eventType": "catalog",
  "type": "Product",
  "interactionName": "catalog-object-click",
  "personalizationId": "2ad68afc-92d3-42f8-88df-d4310f...",
  "personalizationContentId": "2ad68afc-92d3-42f8-88df...",
  "eventId": "14d5d33c-85d6-4ecf-b207-8972f585dcae",
  "dateTime": "2025-08-11T11:54:46.439Z",
  "sessionId": "9fecd3474b94558b",
  "deviceId": "9fecd3474b94558b"
}
```

### Website Engagement

- Use this destination for personalization points that use manual content.
- The event payload uses the `userEngagement` event type.
- The SDK sends the following interaction names by default: `personalization-view` for views and `personalization-click` for clicks.
- Because this destination is for manual content that doesn't correspond to a catalog item, the event payload doesn't contain an `id` or `type` field.

Here's an example payload for a Website Engagement sent to Data Cloud.

```json
{
  "eventType": "userEngagement",
  "eventId": "dcd02e31-8fc4-4b40-918...",
  "dateTime": "2025-05-27T11:56:01.057Z",
  "sessionId": "583f6a8907a88c75",
  "deviceId": "583f6a8907a88c75",
  "interactionName": "Button Clicked",
  "sourceUrl": "https://zzpq-01........",
  "sourceUrlReferrer": "https://zzpq-...",
  "sourceChannel": "Web",
  "sourcePageType": "Default",
  "category": "Engagement"
}
```

## Create a Custom Engagement Destination

While OOTB destinations cover standard scenarios, you may require more control to handle unique tracking requirements or to modify event data. Custom engagement destinations give you granular control over how engagement events are categorized before they're sent to Data Cloud.

To create a custom destination, you add code to your sitemap in a two-step process:

1. [Retrieve the current engagement configuration.](#retrieve-the-current-configuration)
2. [Define and add your custom engagement destination.](#define-and-add-your-custom-destination)

## Retrieve the Current Configuration

First, retrieve the live engagement configuration from the SDK using the `SalesforceInteractions.Personalization.Config.Engagement.get` function.

This function fetches the current configuration object and stores it in a variable, `currentEngagementConfig`, making it available for modification.

## Define and Add Your Custom Destination

Once you've retrieved the configuration object, you can define and add your new destination to its destination property. These parameters make up the engagement destination.

- `label`

  - : A user-friendly name for the destination that appears in the Web Personalization Manager UI.

- `description`

  - : A brief explanation of what this destination is used for. You can also use the label as your description.

- `disableSendingNonItemEngagementEvents`

  - : A boolean that, if set to `true`, denotes that the personalization experience involves recommendations (such as product or article recommendations). If set to `false`, it denotes manual content being recommended.

- `eventModifiers`

  - : An object containing properties that will override the default values in the engagement event payload. The `eventModifiers` object accepts these parameters.

    - `type`

      - : The type of the item being recommended. This is valid only for personalization experiences based on product recommendations.

    - `event-type`

      - : The Data Cloud event type that needs to be mapped to the appropriate DMOs. Ensure that the event type is defined in the Data Cloud web schema and mapped to the correct DMOs.

    - `interaction-name`

      - : Specifies the type of interaction that occurred, such as a view or a click. You can also define this as a function where it receives a single `context` parameter. This `context` object contains a `name` property with a string value of either `view` or `click`, depending on the user's action. You can use this `context.name` value within your function to return custom interaction names.

        ```javascript
        'interaction-name': (context) => {
          switch (context.name) {
          case 'view':
            return 'my-custom-VIEW-interaction-name';
          case 'click':
            return 'my-custom-CLICK-interaction-name';
          default:
            return undefined;
          }
        }
        ```

### Example: Create a Custom Engagement Destination

Here’s a complete example of retrieving the existing configuration, adding a new destination, and applying it during the SDK initialization.

```javascript
// Add a new destination to the current configuration
const currentEngagementConfig = SalesforceInteractions.Personalization.Config.Engagement.get();
currentEngagementConfig.destinations['popupEngagement'] = {
  label: 'Popup Engagement',
  description: 'Popup Engagement',
  disableSendingNonItemEngagementEvents: false,
  eventModifiers: {
    'type': 'Product',
    'event-type': 'userEngagement',
    'interaction-name': (context) => {
      switch (context.name) {
      case 'view':
        return 'my-custom-VIEW-interaction-name'
      case 'click':
        return 'my-custom-CLICK-interaction-name'
      default:
        return undefined
      }
    }
  }
};
// Apply the updated configuration during SDK initialization
SalesforceInteractions.Personalization.Config.initialize({
  ...
  /* Add the custom Engagement Destination */
  customEngagementConfig: currentEngagementConfig
  ...
});
```

## Manually Send Engagement Events

While many out-of-the-box templates handle engagement tracking automatically, you may need to manually send engagement events for custom-built experiences. For this alternative path, use the standard `SalesforceInteractions.sendEvent` function of the Interactions SDK to send engagement events.

For accurate tracking, add the `personalizationId` and `personalizationContentId` values from the personalization response to every engagement event you send manually.

### Example of a Manually Sent Engagement Event

```javascript
SalesforceInteractions.sendEvent({
  interaction: {
    name: "personalization-click",
    eventType: "userEngagement",
    catalogObjectType: "<type of catalog object, for example "Product" or "Category">",
    catalogObjectId: "<catalogObjectId from the personalization response JSON, as applicable>",
    personalization: {
      id: "<personalizationId from the personalization response JSON>",
      contentId: "<personalizationContentId from the personalization response JSON, for a specific product>",
    },
  },
});
```

**note:** Always set `id` and `contentId`. For a specific product, set `contentId` to the `personalizationContentId` value from the JSON response. Otherwise, set it to the `personalizationId`.

<!-- document id=c2170124a6e3d49fa8cd22277ae1fa48f73adb2b24fc1c378725d70fe30f43bb url=/developer/current/en-us/einstein-personalization/einstein-personalization/guides/invocable-actions/show-personalized-recommendations-in-flows.md -->

# Use Personalization Decisions in Flows

Enhance your users' experience by embedding personalized decisions directly within Salesforce Flows using the Get Personalization Decisions invocable action. This action uses the Personalization Decisioning API to retrieve tailored suggestions based on contact information. By configuring the input parameters and using the provided Apex classes, you can show relevant content and product recommendations within your record pages, agent consoles, and other Flow-driven processes.

## Example: Retrieve and Show Personalization Content for a Contact Record

This example describes how to use the Get Personalization Decisions invocable action to configure a flow that retrieves and displays personalization content for a contact record.

### Prerequisites

Before you begin, make sure you have:

- A [fully configured personalization point](https://help.salesforce.com/s/articleView?id=mktg.mc_persnl_personalization_point_configure.htm)
- A Data Cloud data space with unified individual data

### Create a Screen Flow

1. From **Setup**, in the Quick Find box, enter Flows.
2. Select **Flows** and then **New Flow**.
3. Select **Start from Scratch** and click **Next**.
4. Select **Screen Flow** and then click **Create**.

### Add Apex Resources

To map values from your contact record and personalization point to the Get Personalization Decisions action and then show the result to a screen, add the default Apex classes to your Flow.

1. Open the **Toolbox** and click **New Resource**.
2. From the Resource Type dropdown, select **Variable**.
3. Provide an API Name. For example, `persnlDecInpRep`.
4. From the Data Type dropdown, select **Apex-Defined**.
5. Leave **Allow multiple values (collection)** unchecked.
6. Search for and select the Apex class `ConnectApi__PersnlDecisionInputRepresentation`.
7. Check **Available for input** and then click **Done**.
   ![Create an Apex-defined Variable](https://developer.salesforce.com/media/create-apex-variable.png)
8. Repeat the preceding steps to create these resources.

   | Apex Class                                       | Example API Name      | Purpose                                                                                                                      |
   | ------------------------------------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
   | `ConnectApi__PersnlDecisionOutputRepresentation` | `persnlDecOutRep`     | To reference personalized data, recommendations, and diagnostics information when displaying the output to a Contact record. |
   | `ConnectApi__PersnlPointInputRepresentation`     | `pesrnlPointVariable` | Variable for personalization point names.                                                                                    |

### Add a Variable for a Contact Resource

To pass the Contact's ID through the Flow a variable is needed to store it.

1. Click **New Resource**.
2. From the Resource Type dropdown, select **Variable**.
3. Under **API Name**, enter `recordId`.
4. From the **Data Type** dropdown, select **Record**.
5. Under **Object**, search for and select **Contact**.
6. Check **Available for input** and then click **Done**.

### Assign the Record ID to \$Flow.CurrentRecord

Assign the ID from the Contact to the variable. This variable will be used to find the Unified Individual in Data Cloud.

1. After the Screen Flow element, add an Assignment element.
2. Enter a **Label** and **API Name**.
3. Under Variable, search for and select the Flow global variable for Current Record `{!$Flow.CurrentRecord}`.
4. For **Operator**, leave **Equals** selected.
5. Under Value, choose the variable you created for the Contact resource `{!recordId.Id}.`

For more information on adding record context to your flows, see [Add Record Context to Your Flows](https://help.salesforce.com/s/articleView?id=platform.flow_pause_recordassoc.htm). For considerations to keep in mind before using flow actions, see [Flow Action Considerations](https://help.salesforce.com/s/articleView?id=platform.flow_actions_considerations.htm).

### Add Personalization Point Resources

For your flow to correctly identify and reference the specific personalization point you've configured, you'll need to add personalization point resources.

1. Open the Toolbox and click **New Resource**.
2. From the Resource Type dropdown, select **Variable**.
3. Enter an API Name. For example, `PersnlPoint_ApiName_Action_Input`.
4. From the **Data Type** dropdown, select **Text**.
5. Set Default Value to the API name of your personalization point, and then click **Done**.

**note:** The personalization point type determines the output format. Use a **Recommendations** type personalization point to retrieve product recommendations, or a **Manual Content** type personalization point to retrieve content attributes.

### Get Unified Individual Data from Data Cloud

1. Add a Get Records element after the Assignment element. This element finds the unified individual data from Data Cloud that matches the contact information.
2. For Label, enter `Get Unified Individual for Contact Record`.
3. Select **Data Cloud Object** as the Data Source.
4. Use the Data Space dropdown to select the data space you'd like to use.
5. Under Object, search for and select your unified individual data model object (DMO). For example, `Unified Individual`.
6. For Condition Requirements, select **All Conditions Are Met (AND)**.
7. Under Field, search for and select the field that represents a contact's first name. For example, `ssot__FirstName__c`.
8. For Operator, select **Equals**.
9. For Value, select the variable for the contact record and the attribute for First Name: `{!recordId.FirstName}`.
10. Click **Add Condition**.
11. Under Field, search for and select the field that represents a contact's last name. For example, `ssot__LastName__c`.
12. For Operator, select **Equals**.
13. For Value, select the variable for the contact record and the attribute for Last Name: `{!recordId.LastName}`.
14. Leave the rest of the configuration as is.

### Get Unified Link Individual ID from Data Cloud

1. Add another Get Records element after the Get Records element for unified individual data. This Get Records element finds the unified link individual from Data Cloud that matches the contact information.
2. For Label, enter `Get Unified Link Individual`.
3. Select **Data Cloud Object** as the Data Source.
4. Use the Data Space dropdown to select the data space you'd like to use.
5. Under Object, search for and select your unified link individual DMO. For example, `Unified Link Individual`.
6. For Condition Requirements, select **All Conditions Are Met (AND)**.
7. Under Field, search for and select the unique ID for the Unified Individual: `UnifiedRecordId__c`
8. For Operator, select **Equals**.
9. For Value, search for and select the Unified Individual ID that is retrieved from the record fetched by the Get Records element for Unified Link Individual: `{!Get_Unified_Individual.ssot__Id__c}`.

### Assign Inputs

Follow these steps to map the `individualID` you retrieved from Data Cloud and the personalization point from the input screen to `ConnectApi__persnlDecisionInputRepresentation`.

1. Add an Assignment element after the Get Records element for Unified Link Individual ID.
2. For Label, enter `Personalization Point and Individual ID Assignment`.
3. Under Set Variable Values, configure these assignments:
   | Assignment | Operator | Example Assignment |
   |---|---|---|
   | Assign the Apex-defined variable for personalization point name (the one associated to the Apex Class `ConnectApi__PersnlPointInputRepresentation`) to the personalization point resource | Equals | `{!pesrnlPointVariable.persnlPointName}` Equals `{!PersnlPoint_ApiName_Action_Input}` |
   | Assign the list of personalization points from the Apex-defined variable for `ConnectApi__PersnlDecisionInputRepresentation` to the variable for personalization point names | Add | `{!persnlDecInpRep.personalizationPoints}` Add `{!pesrnlPointVariable}` |
   | Assign `context.individualId` from the Apex-defined variable for `ConnectApi__PersnlDecisionInputRepresentation` to the unified individual ID retrieved by the second Get Records element | Equals | `{!persnlDecInpRep.context.individualId}` Equals `{!Get_Unified_Individual.ssot__Id__c}` |

### Add and Configure the Get Personalization Decisions Action

Next, pass in the variable you created in the previous step into the Get Personalization Decisions invocable action.

1. Search for and add a Get Personalization Decisions invocable action after the Assignment element.
2. Enter a Label.
3. In the Personalization Decision Input field, select the Apex resource you created for the `ConnectApi__PersnlDecisionInputRepresentation` Apex class.
4. Enable **Included with Specified Value**.
5. Under Invocation Type, enter `FLOW`.
6. Expand **Show advanced options**.
7. Check **Manually assign variables**.
8. In the Personalization Decision Output field, select the Apex resource created for the `ConnectApi__PersnlDecisionOutputRepresentation` Apex class.

### Loop Through the Personalization Decision Output Collection

To process the personalization decisions retrieved by the Get Personalization Decisions invocable action, add two Loops to the flow. The first loop iterates through the `persnlDecisionOutputRepresentation.personalizations` collection. The second loop iterates through a collection within each `personalization` object, depending on your personalization point type.

1. Add the first Loop element after the Get Personalization Decisions action.
2. Provide a Label. For example, `Loop1`.
3. Under Collection Variable, select `{!persnlDecisionOutputRepresentation.personalizations` to loop through the collection.
4. Specify the direction for iterating over the collection as you deem appropriate.
5. Add another Loop element immediately after the first Loop.
6. Provide a Label.
7. Under Collection Variable, select the appropriate collection variable from your first loop based on your personalization point type:
   - **Recommendations**: Select `{!Loop1.persnlRecommendations}` to iterate through product recommendations.
   - **Manual Content**: Select `{!Loop1.contentAttributes}` to iterate through content attributes.
8. Specify the direction for iterating over the collection.

### Add a Screen Element to Show the Output

In this step, you'll add a Screen element to show the personalization decisions to your users on the Contact page.

1. Add a Screen element after the second Loop and label it.
2. Add a **Repeater** component to the canvas and provide an API Name.
3. Drag a **Display Text** component within the Repeater component and provide an API Name.
4. Use the **Insert a resource…** field to search for and insert resources to show your results as shown in the examples below.

   **note:** These examples use resource names and values referenced in this article.

#### For Recommendations Type Personalization Points

```
Personalization Point Name: {!Loop1.persnlPointName}

Personalization Point Attributes: {!Loop1.attributes}

Unified Individual: {!Get_Unified_Individual.ssot__Id__c}

Individual ID: {!Get_Link_Individual.SourceRecordId__c}

Name: {!Get_Unified_Individual.ssot__FirstName__c} {!Get_Unified_Individual.ssot__LastName__c}

Request ID: {!persnlDecOutRep.requestId}

Recommendations: {!Loop1.persnlRecommendations}

Recommendations from persnlRecommendations Collection: {!Loop2.additionalProperties}

Diagnostics: {!persnlDecOutRep.diagnostics}
```

#### For Manual Content Type Personalization Points

```
Personalization Point Name: {!Loop1.persnlPointName}

Personalization Point Attributes: {!Loop1.attributes}

Unified Individual: {!Get_Unified_Individual.ssot__Id__c}

Individual ID: {!Get_Link_Individual.SourceRecordId__c}

Name: {!Get_Unified_Individual.ssot__FirstName__c} {!Get_Unified_Individual.ssot__LastName__c}

Request ID: {!persnlDecOutRep.requestId}

Attributes: {!Loop1.contentAttributes}

Attribute Name from contentAttributes Collection: {!Loop2.attributeName}
Attribute Value from contentAttributes Collection: {!Loop2.attributeValue}
Diagnostics: {!persnlDecOutRep.diagnostics}
```

5. **Save** and **Activate** your flow.

### Add Screen Flow to a Contact Page

Finally, to add personalization decisions to your Contact page, edit the page by following these instructions.

1. Exit Flow Builder and go to **Contacts**.
2. Click any contact.
3. Click the settings cog and then click **Edit Page**.
4. Drag the flow component you created onto the page canvas.
5. Select the flow you just created.
6. Check **Pass all field values from the record into this flow variable**.
7. Click **Save**.

A fully configured flow that retrieves and displays personalized recommendations for a contact record looks like this.

![Fully-configured flow that retrieves and displays personalization decisions](https://developer.salesforce.com/media/complete-flow-get-personalization-decisions-invocable-action.png)