# developer Marketing Cloud Personalization (personalization) - Full Documentation

<!-- document id=54c9c3da0159e2b27946e56e100f10c8d74a9bcebc089c5924bae0ad73b3859b url=/developer/current/en-us/personalization/personalization/guides/additional-apis/account-export-api.md -->

# Account Export API

The Marketing Cloud Personalization Account Export API helps you retrieve account-level data from datasets such as segments, engagement scores, change in engagement scores, and customer activity for use in other systems.

Your Personalization contract defines the volume of records you can export using the Account Export API. For more information, refer to your contract or contact your account representative.

**important:** Account Profiles was retired in August 2024. For more information, see [Personalization Account Profiles Retirement](https://help.salesforce.com/s/articleView?id=001744617&type=1).

## Exporting Account Data via API

Export account data from a Personalization dataset.

### Method and Endpoint

`GET` `/api/dataset/<datasetId>/accounts.< json | csv >`

### Request URL

`https://<accountName>.<instance>.evergage.com/api/dataset/<datasetId>/accounts.< json | csv >`

### Request Parameters

| URL Parameter    | Required? | Description                                                                                                                                                                                                                                            |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `accountName`    | Yes       | The Personalization account name. You can find the `accountName` by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the account name is `demo`.        |
| `instance`       | Yes       | The Personalization instance identifier. You can find this value by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the instance identifier is `us-1`. |
| `datasetId`      | Yes       | The name or identifier of the Personalization dataset you’re exporting account data from.                                                                                                                                                              |
| `filter`         | No        | Optional Segment name or ID                                                                                                                                                                                                                            |
| `start`          | No        | Optional start time in epoch milliseconds used for engagement statistics                                                                                                                                                                               |
| `end`            | No        | Optional end time in epoch milliseconds used for engagement statistics                                                                                                                                                                                 |
| `segmentationId` | No        | Optional segmentation identifier                                                                                                                                                                                                                       |
| `segmentId`      | No        | Optional segment identifier                                                                                                                                                                                                                            |
| `pageSize`       | No        | Number of records to return. Returns all records unless specified.                                                                                                                                                                                     |
| `page`           | No        | Page number of records to show, starting at zero for the first page. Starts at zero unless specified.                                                                                                                                                  |

### Authorization

`Authorization: Basic <base64-encoded-API-token>`

The Account Export API uses API tokens to authenticate requests. Your API token must be a strict Base64 encoding of your API Key ID and its API Secret Key, separated by a colon. You can use an existing API token if it has the required permissions. Alternatively, you can ask an account administrator to generate a new one from the Personalization UI. For more information on API tokens, see [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm) on Salesforce Help.

Alternatively, if you use [cURL](https://curl.se/docs/manpage.html) to interact with the API, you can send your API Key ID and its API Key Secret using the `-u "apiKeyId:apiKeySecret"` command-line option. cURL automatically converts the `apiKeyId:apiKeySecret` pair into a Base64-encoded string and adds the `Authorization: Basic <base64-encoded-API-token>` to the request header. For an example of how to pass your API credentials in a cURL request, refer to the [Example](#example) section in this article.

### Example

The following is an example GET request sent using cURL that retrieves account data in the JSON format from the specified Personalization dataset.

**note:** The following example request passes API credentials using the `-u` command-line option.

```bash
curl -u "apiKeyId:apiKeySecret" \
     "https://<accountName>.<instance>.evergage.com/api/dataset/<datasetId>/accounts.json"
```

The preceding example cURL request generates the following example response in the JSON format.

```json
[
  {
    "name": "Acme, Inc.",
    "engagementScore": 0.546,
    "engagementPercentChange": -0.138,
    "firstActivity": 1358640000000,
    "lastActivity": 1360195200000,
    "totalActions": 51,
    "accountStatus": "premium",
    "attributes": {},
    "accountName": "Acme, Inc.",
    "activeUsers": 3,
    "segments": []
  }
]
```

## See Also

- _Salesforce Help_: [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm)

<!-- document id=6d342370a7b856c53c791405a385ea5018c8c207f7710fe5b8bd16e996b99834 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/open-time-email-campaigns-templates/third-party-tracking-for-email-campaigns.md -->

# Add Third Party Tracking Parameters to Open Time Email Campaigns

Urchin Tracking Module (UTM) parameters are tags that you can add to the end of a URL to track its performance and know its traffic sources. Adding UTM parameters to URLs in your Open Time Email Campaigns can give you more detailed insights into your campaign's performance. While Marketing Cloud Personalization provides analytics and full campaign performance reporting, you can still use your existing web analytics system to monitor clickthrough traffic with your Open Time Email campaigns. To learn more about how you can combine third-party tracking data with data from Personalization, talk to your Salesforce account representative.

This article describes how to use UTM parameters with Open Time Email Campaigns. To know more about Open Time Email Campaigns, or how to create one, see [Open Time Email Campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_email_campaign.htm) on Salesforce Help. Before reading the instructions in this article, make sure you've created or cloned an Open Time Email campaign, tested it, and have its HTML code open in front of you.

## Add UTM Parameters to Your Emails

To add UTM parameters to your emails, do the following.

1. Access the Open Time Email campaign within the Campaign Edit screen in the Personalization UI. For detailed instructions on accessing the Campaign Edit screen, see [Create an Open Time Email Campaign](https://help.salesforce.com/s/articleView?id=sf.mc_pers_email_campaign_create.htm) on Salesforce Help.
2. Click **SIMULATE** > **Show HTML**.
3. Identify the URLs to track in your email campaign. We recommend tracking URLs for item recommendations included in your email template along with any other URLs of importance.
4. Append UTM parameters at the end of each identified URL, starting with and separated by the `&` symbol. Excluding the `&` symbol breaks the URL and leads to improper tracking. For example, if the URL of an item in your email is `https://demo.evergage.com/api/dataset/engage/campaign/YnFdJ/N7pF1/1/detail?userId=@@USER_ID@@`, add the UTM parameters at the end of the URL as shown in the following example.

   ```
   https://demo.evergage.com/api/dataset/engage/campaign/YnFdJ/N7pF1/1/detail?userId=%40%40USER_ID&utm_source=newsletter&utm_medium=email&utm_campaign=lead_generation
   ```

After you've added UTM parameters to all relevant URLs, use the updated campaign HTML with your email marketing solution to send your campaign to recipients. With the UTM parameters you added, you can track your campaign's clickthrough rates directly in your web analytics system.

## URL Encoding in UTM Parameters

To ensure that URLs resolve correctly, you must encode all non-ASCII characters and the following reserved ASCII characters when using them in UTM parameters.

| ASCII Character | URL Encoding |
| --------------- | ------------ |
| `!`             | `%21`        |
| `#`             | `%23`        |
| `$`             | `%24`        |
| `'`             | `%27`        |
| `(`             | `%28`        |
| `)`             | `%29`        |
| `*`             | `%2A`        |
| `+`             | `%2B`        |
| `,`             | `%2C`        |
| `/`             | `%2F`        |
| `:`             | `%3A`        |
| `;`             | `%3B`        |
| `=`             | `%3D`        |
| `?`             | `%3F`        |
| `@`             | `%40`        |
| `[`             | `%5B`        |
| `\|`            | `%5C`        |
| `]`             | `%5D`        |

## Example

The following code sample contains HTML for a row of three item recommendations in an Open Time Email campaign. This sample HTML is for illustrative purposes only and includes an illustrative dynamic variable `@@USER_ID@@` for `userId`. Your email marketing solution could use a different dynamic variable format.

**note:** Depending on your email marketing solution, you may have to modify the item and item image URLs in your Open Time Email campaign. For more information on capturing and modifying campaign URLs, refer to [Capture an Open Time Email Campaign URL](https://developer.salesforce.com/docs/marketing/personalization/guide/capture-email-campaign-url.md).

```html
<!-- start Personalization Recommendations block (Item Recommendations Row 1) -->
<table
  cellspacing="0"
  cellpadding="0"
  border="0"
  align="center"
  width="100%"
  style="table-layout: fixed;"
>
  <tbody>
    <tr>
      <td width="100%">
        <div
          class="evergage-block"
          style="max-height: 100%; max-width: 100%; position: relative; overflow: hidden; text-align: center;"
        >
          <div class="evergage-recs" style="display: table; width: 100%; max-height: 100%;">
            <!--Item 1-->
            <span class="evergage-rec" style="display: inline-block;">
              <a
                href="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/1/detail?userId=@@USER_ID@@"
              >
                <img
                  src="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/1/summary.png?userId=@@USER_ID@@"
                  style="max-width: 100%; border: 0;"
                  border="0"
                  alt="Item image"
                />
              </a>
            </span>
            <!--Item 2-->
            <span class="evergage-rec" style="display: inline-block;">
              <a
                href="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/2/detail?userId=@@USER_ID@@"
              >
                <img
                  src="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/2/summary.png?userId=@@USER_ID@@"
                  style="max-width: 100%; border: 0;"
                  border="0"
                  alt="Item image"
                />
              </a>
            </span>
            <!--Item 3-->
            <span class="evergage-rec" style="display: inline-block;">
              <a
                href="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/3/detail?userId=@@USER_ID@@"
              >
                <img
                  src="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/3/summary.png?userId=@@USER_ID@@"
                  style="max-width: 100%; border: 0;"
                  border="0"
                  alt="Item image"
                />
              </a>
            </span>
          </div>
        </div>
      </td>
    </tr>
  </tbody>
</table>
<!-- end Personalization Recommendations block (Item Recommendations Row 1) -->
```

The goal of this example is to track the traffic source of item URLs in the campaign. To do so, we'll append the UTM parameters `utm_source=newsletter`, `utm_medium=email`, and `utm_campaign=lead_generation` at the end of each item URL, after `detail?userId=@@USER_ID@@"`.

The sample campaign HTML after adding UTM parameters to each item URL is as shown in the following example.

```html
<!-- start Personalization Recommendations block (Item Recommendations Row 1) -->
<table
  cellspacing="0"
  cellpadding="0"
  border="0"
  align="center"
  width="100%"
  style="table-layout: fixed;"
>
  <tbody>
    <tr>
      <td width="100%">
        <div
          class="evergage-block"
          style="max-height: 100%; max-width: 100%; position: relative; overflow: hidden; text-align: center;"
        >
          <div class="evergage-recs" style="display: table; width: 100%; max-height: 100%;">
            <!--Item 1-->
            <span class="evergage-rec" style="display: inline-block;">
              <a
                href="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/1/detail?userId=@@USER_ID@@&utm_source=newsletter&utm_medium=email&utm_campaign=lead_generation"
              >
                <img
                  src="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/1/summary.png?userId=@@USER_ID@@"
                  style="max-width: 100%; border: 0;"
                  border="0"
                  alt="Item image"
                />
              </a>
            </span>
            <!--Item 2-->
            <span class="evergage-rec" style="display: inline-block;">
              <a
                href="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/2/detail?userId=@@USER_ID@@&utm_source=newsletter&utm_medium=email&utm_campaign=lead_generation"
              >
                <img
                  src="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/2/summary.png?userId=@@USER_ID@@"
                  style="max-width: 100%; border: 0;"
                  border="0"
                  alt="Item image"
                />
              </a>
            </span>
            <!--Item 3-->
            <span class="evergage-rec" style="display: inline-block;">
              <a
                href="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/3/detail?userId=@@USER_ID@@&utm_source=newsletter&utm_medium=email&utm_campaign=lead_generation"
              >
                <img
                  src="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/3/summary.png?userId=@@USER_ID@@"
                  style="max-width: 100%; border: 0;"
                  border="0"
                  alt="Item image"
                />
              </a>
            </span>
          </div>
        </div>
      </td>
    </tr>
  </tbody>
</table>
<!-- end Personalization Recommendations block (Item Recommendations Row 1) -->
```

## See Also

- _Salesforce Help_: [Open Time Email Campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_email_campaign.htm)
- _Salesforce Help_: [Create an Open Time Email Campaign](https://help.salesforce.com/s/articleView?id=sf.mc_pers_email_campaign_create.htm)

<!-- document id=dd718215ffb22017912acdc98aa90a0603343fd4b033beabd029868172edbf04 url=/developer/current/en-us/personalization/personalization/guides/additional-apis/additional-personalization-apis.md -->

# Additional APIs

Marketing Cloud Personalization provides the following additional APIs that let you interact with and retrieve data from your Personalization instance, and also perform housekeeping tasks on your Personalization instance as needed.

- [Account Export API](https://developer.salesforce.com/docs/marketing/personalization/guide/account-export-api.md) - Export account data from Personalization datasets.
- [Audit Log API](https://developer.salesforce.com/docs/marketing/personalization/guide/audit-log-api.md) - Retrieve access and activity logs from your Personalization instance.
- [Principals API](https://developer.salesforce.com/docs/marketing/personalization/guide/principals-api.md) - Retrieve list of Personalization Principals.
- [User Export API](https://developer.salesforce.com/docs/marketing/personalization/guide/user-export-api.md) - Export user data from Personalization datasets.
- [User Look-Up & Deletion API](https://developer.salesforce.com/docs/marketing/personalization/guide/user-look-up-deletion-api.md) - Service _Right to Access_ and _Right to be Forgotten_ requests received from customers.

<!-- document id=db7e4bf33f6c28b510a1716f064f77ff3edfe9f4bb504c033900deee7cdffde8 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/advanced-dynamic-message-content/advanced-dynamic-message-content-cheatsheet.md -->

# Advanced Dynamic Content Cheatsheet

This section details the variables used for advanced dynamic messages.

## Users

| Variable                         | Type   | Description                     |
| -------------------------------- | ------ | ------------------------------- |
| `${user.id}`                     | String | User ID                         |
| `${user.userName}`               | String | Name                            |
| `${user.userNameOrAnonLocation}` | String | Name or "user from City, State" |
| `${user.accountType}`            | String | Account type                    |
| `${user.emailAddress}`           | String | Email address                   |

### User Location

| Variable                             | Type    | Description                                        |
| ------------------------------------ | ------- | -------------------------------------------------- |
| `${user.location.postalCode}`        | String  | ZIP code                                           |
| `${user.location.city}`              | String  | City                                               |
| `${user.location.metro}`             | String  | Metro area                                         |
| `${user.location.metroCode}`         | Integer | Metro code                                         |
| `${user.location.region}`            | String  | State/region                                       |
| `${user.location.stateProvinceCode}` | String  | State/region code (shorthand)                      |
| `${user.location.country}`           | String  | Country                                            |
| `${user.location.countryCode}`       | String  | Country code (shorthand)                           |
| `${user.location.organization}`      | String  | Organization                                       |
| `${user.location.industry}`          | String  | Industry                                           |
| `${user.location.naicsCode}`         | Integer | North American Industry Classification System code |

### User Custom

| Variable                       | Description                                               |
| ------------------------------ | --------------------------------------------------------- |
| `${user.attributes._________}` | Custom Attribute (Use dropdown in editor for specific ID) |

## Items

Things that count as items:

- Products
- Articles
- Blogs
- Catalog Objects
- Categories

### Basic

Must have intended item query selected in message settings

| Variable                          | Type              | Description                                            |
| --------------------------------- | ----------------- | ------------------------------------------------------ |
| `${item}`                         | Object            | Item object                                            |
| `${items}`                        | Array             | Array of item objects                                  |
| `${items[0]}...${items[9]}`       | Object            | Item in array                                          |
| `${page.item}`                    | Object            | Current page item object                               |
| `${page.category}`                | Object            | Current page category or category of current page item |
| `${item.name}`                    | String            | Item name                                              |
| `${item.id}`                      | String or Integer | Item ID                                                |
| `${item.url}`                     | String            | Item URL                                               |
| `${item.imageUrl}`                | String            | Image URL                                              |
| `${item.description}`             | String            | Item description                                       |
| `#field(${item.rating}, '0')`     | Integer           | Average rating                                         |
| `#field(${item.numRatings}, '0')` | Integer           | Number of ratings                                      |
| `${item.categories}`              | Array             | Categories objects                                     |
| `${item.dimensions}`              | Array             | All related Catalog Objects                            |

| Custom Variables                 | Description                                      |
| -------------------------------- | ------------------------------------------------ |
| `${item.attributes.xxxxx.value}` | Value of the attribute named "xxxxx" on the item |

### Products Only

| Variable                   | Type    | Description                                                                           |
| -------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `${item.price}`            | Integer | Price. **NOTE**: Unformatted. For more information, see [Utilities](#utilities).      |
| `${item.priceDescription}` | String  | Price description                                                                     |
| `${item.listPrice}`        | Float   | List price. **NOTE**: Unformatted. For more information, see [Utilities](#utilities). |
| `${item.inventoryCount}`   | Integer | Inventory count                                                                       |
| `${item.brands}`           | Array   | Brand tag objects                                                                     |
| `${item.classes}`          | Array   | Class tag objects                                                                     |
| `${item.styles}`           | Array   | Style tag objects                                                                     |
| `${item.genders}`          | Array   | Gender tag objects                                                                    |

## Build Item Query in Message (Advanced)

### Query Type: Global/User Interchangeable

| Variable                        | Description             |
| ------------------------------- | ----------------------- |
| `${tools.global...}`            | Query Global Statistics |
| `${tools.user...}`              | Query User Statistics   |
| `${tools.global.products...}`   | Query Products          |
| `${tools.global.articles...}`   | Query Articles          |
| `${tools.global.blogs...}`      | Query Blogs             |
| `${tools.global.categories...}` | Query Categories        |
| `${tools.global.brands...}`     | Query Brands            |
| `${tools.global.styles...}`     | Query Styles            |
| `${tools.global.authors...}`    | Query Authors           |
| `${tools.global.keywords...}`   | Query Keywords          |

### Query: Default Array Length Min 1 Max 5

| Variable                                   | Type  | Description                             |
| ------------------------------------------ | ----- | --------------------------------------- |
| `${tools.global.products.viewCount()}`     | Array | Top viewed products by count            |
| `${tools.global.products.viewTime()}`      | Array | Top viewed products by time             |
| `${tools.global.products.cartCount()}`     | Array | Products most added to cart by count    |
| `${tools.global.products.cartValue()}`     | Array | Products most added to cart by currency |
| `${tools.global.products.purchaseCount()}` | Array | Top purchased products by count         |

Ensure that you either iterate over every product in an array

### Global Only

| Variable                                   | Type  | Description                     |
| ------------------------------------------ | ----- | ------------------------------- |
| `${tools.global.products.publishedDate()}` | Array | Most recently published product |

### User Only

| Variable                                  | Type  | Description                                                                        |
| ----------------------------------------- | ----- | ---------------------------------------------------------------------------------- |
| `${tools.user.products.viewed()}`         | Array | Most Recently Viewed                                                               |
| `${tools.user.orders.currentItems()}`     | Array | Products in cart. **Note**: Personalization doesn’t currently track cart removals. |
| `${tools.user.orders.currentValue()}`     | Float | Total cart value. **Note**: Unformatted, see utilities.                            |
| `${tools.user.get('Engagement', 'none')}` |       | User's Engagement Score                                                            |

## Item Options

You can further refine results from query functions by passing them a set of item options, as shown in the following example.

```html
$tools.user.products.viewCount(${itemOptions...})
```

You can specify item options by calling multiple functions on the `itemOptions` object, as shown in the following example.

```html
${itemOptions.optionOne().optionTwo().optionThree()}
```

### Sizes

By default, a message containing advanced dynamic queries renders only if there's at least 1 result.

To increase the minimum number of items returned, use `${itemOptions.minItems(<Integer>)}`.

To increase the maximum number of items returned, use `${itemOptions.maxItems(<Integer>)}`.

**note:** You can’t increase the maximum number of items returned beyond 10.

### Filters

You can further filter query results using the following filters.

| Filter                                                                            | Description                                                                                                                                         |
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `${itemOptions.withCategory(<CategoryID>)}`                                       | Filter results by the category the visitor is currently viewing.                                                                                    |
| `${itemOptions.withBrand(<BrandID>)}`                                             | Filter results to contain only items with a specific brand.                                                                                         |
| `${itemOptions.withBrandAnyOf([<BrandID1>,<BrandID2>,...])}`                      | Filter results to contain items from any of the specified brands.                                                                                   |
| `${itemOptions.withGender(<GenderID>)}`                                           | Filter results by gender.                                                                                                                           |
| `${itemOptions.withGenderAnyOf([<GenderID1>,<GenderID2>,...])}`                   | Filter results by any of the specified gender IDs.                                                                                                  |
| `${itemOptions.withKeyword(<KeywordID)}`                                          | Filter results by a specified keyword.                                                                                                              |
| `${itemOptions.withKeywordAnyOf([<KeywordID1>,<KeywordID2>,...])}`                | Filter results by any of the specified keywords.                                                                                                    |
| `${itemOptions.withAuthor(<AuthorID)}`                                            | Filter results by `AuthorID`.                                                                                                                       |
| `${itemOptions.withAuthorAnyOf([<AuthorID1>,<AuthorID2>,...)}`                    | Filter results by any of the specified authors.                                                                                                     |
| `${itemOptions.withContentClass(<ContentClassID>)}`                               | Filter results by `ContentClassID`.                                                                                                                 |
| `${itemOptions.withContentClassAnyOf([<ContentClassID1>,<ContentClassID2>,...])}` | Filter results by any of the specified content classes.                                                                                             |
| `${itemOptions.withStyle(<StyleID>)}`                                             | Filter results by style.                                                                                                                            |
| `${itemOptions.withStyleAnyOf([<StyleID1>,<StyleID2>,...])}`                      | Filter results by any of the specified styles.                                                                                                      |
| `${itemOptions.withItemClass(<ItemClassID>)}`                                     | Filter results by item class.                                                                                                                       |
| `${itemOptions.withItemClassAnyOf([<ItemClassID1>,<ItemClassID2>,...])}`          | Filter results by any of the specified item classes.                                                                                                |
| `${itemOptions.whereCreated(<TimeObject>)}`                                       | Filter results by date or time range of creation. To know more about the available `TimeObject` functions, see [Lookback Period](#lookback-period). |
| `${itemOptions.wherePublished(<TimeObject>)}`                                     | Filter results by published or time range. To know more about the available `TimeObject` functions, see [Lookback Period](#lookback-period).        |

### Lookback Period

To specify a lookback period apart from the default lookback period of the past week, use:

```handlebars
${itemOptions.time(<TimeObject>)}
```

The following functions are provided by the `$time` singleton object:

| Function       | Description                                                                      |
| -------------- | -------------------------------------------------------------------------------- |
| `today`        | Today                                                                            |
| `thisWeek`     | Current calendar week (with Monday as first day of week)                         |
| `thisMonth`    | Current calendar month                                                           |
| `since(date)`  | Since the specified date; date format is “mm/dd/yyyy” (for example “07/07/2017”) |
| `lastNDays(n)` | Last n days, including today; lastNDays(1) would mean today and yesterday        |
| `allTime`      | Don’t define a specific date range                                               |

### Conditional Options

The `itemOptions` object provides several conditional options or methods that you can call to filter or manipulate its properties based on certain conditions.

| Conditional Option                          | Description                                  |
| ------------------------------------------- | -------------------------------------------- |
| `${itemOptions.whereName()...}`             | Filter data based on item name.              |
| `${itemOptions.whereDescription()...}`      | Filter data based on item description.       |
| `${itemOptions.whereUrl()...}`              | Filter data based on item URL.               |
| `${itemOptions.whereImageUrl()...}`         | Filter data based on an item's image URL.    |
| `${itemOptions.wherePriceDescription()...}` | Filter data based on item price description. |

#### Conditionals

You can use conditionals with conditional options to further refine the data being filtered.

```handlebars
${itemOptions.whereName().exists()}
```

The following conditionals are available for use.

| Conditional                | Description                                                                      |
| -------------------------- | -------------------------------------------------------------------------------- |
| `exists()`                 | Checks whether the property being filtered exists.                               |
| `doesNotExist()`           | Checks whether the property being filtered doesn’t exist.                        |
| `contains(<String>)`       | Checks whether the property being filtered contains the specified string.        |
| `doesNotContain(<String>)` | Checks whether the property being filtered doesn’t contain the specified string. |

### Sorting

To sort the results for display, use the `displaySort` function.

```handlebars
${itemOptions.displaySort(<SortOptions>)}
```

To sort results for display in the descending order, use the `descending` function.

```handlebars
${itemOptions.descending()}
```

The `displaySort` function provides the following sort options.

| Sort Option                      | Description                      |
| -------------------------------- | -------------------------------- |
| `${productSort.name()}`          | Sort products by name.           |
| `${productSort.price()}`         | Sort products by price.          |
| `${articleSort.name()}`          | Sort articles by name.           |
| `${articleSort.publishedDate()}` | Sort articles by published date. |
| `${blogSort.name()}`             | Sort blogs by name.              |
| `${blogSort.publishedDate()}`    | Sort blogs by published date.    |

To sort results for display in the descending order, use the `descending` function.

```handlebars
${itemOptions.descending()}
```

### Inclusions

To include items a visitor is currently viewing in query results, use:

```handlebars
${itemOptions.includeItemsBeingViewed()}
```

To include items in a visitor's cart in query results, use:

```handlebars
${itemOptions.includeItemsInCart()}
```

### Exclusions

To exclude items a visitor has already purchased from query results, use:

```handlebars
${itemOptions.excludePurchasedItems()}
```

To exclude items a visitor has already viewed from query results, use:

```handlebars
${itemOptions.excludeViewedItems()}
```

## Utilities

### If/Else Statements

```html
<!-- #if ($user.attributes.firstName) -->
<div>Hello $user.attributes.firstName</div>
<!-- #else -->
<div>You don't have a first name at all</div>
<!-- #end -->
```

### Set Variables

```handlebars
#set (${variableName} = $...)
```

### Loops

```handlebars
#foreach (${variableName} in <Array>)
...
#end
```

### Format Price

There are two ways to format prices.

- By passing the price as a floating-point number to the `formatPrice` method. The `formatPrice` method formats the given number as a price, with the default dataset currency symbol and appropriate decimal formatting, and returns the formatted string.

  ```handlebars
  $tools.formatPrice(<Float>)
  ```

  **important:** In Open Time Email Templates, only the `$currencyTools.formatPrice(<Float>)` method is available. This method is used instead of is used instead of the `$tools.formatPrice(<Float>)` and `$tools.formatNumber(<Float>, <Int Number of Fractional Digits>)` methods.

- By passing the price as a floating-point number and a fixed number of digits after the decimal point to the `formatNumber` method.

  ```handlebars
  $tools.formatNumber(<Float>, <Int Number of Fractional Digits>)
  ```

### Field

The `#field` utility enables you to provide a fallback value for an attribute.

```html
<div>#field($item.attributes.testString, "Item does not have a testString attribute")</div>
```

<!-- document id=212a4f33b2b5717cfa5f636782720e005afae86a70ece90d57c421095e31bf5c url=/developer/current/en-us/personalization/personalization/guides/campaign-development/advanced-dynamic-message-content/advanced-dynamic-message-content.md -->

# Advanced Dynamic Message Content Reference

Dynamic Message Content (DMC) allows you to insert personalized content into your Marketing Cloud Personalization Open Time Email and Mobile Data campaign messages in real time. When you enable and use DMC, you can insert placeholders into a message that are replaced with the corresponding values for the receiving audience. However, there are cases where DMC placeholders aren’t configurable enough to cater to specific or advanced requirements.

In such cases, you can use Advanced Dynamic Message Content (ADMC) syntax to gain greater flexibility and control over the dynamic message content. ADMC offers variables for additional configurability so you can address specific or complex campaign requirements. You can use ADMC to query Personalization to return a specific set of items or content that matches certain criteria, and to further refine your query results.

Overall, ADMC helps create engaging messages for campaign audiences, whether providing product recommendations, promoting related content, or offering targeted promotions.

**important:** We suggest enlisting the help of experienced developers while using ADMC in your campaigns. If you’re unsure of any requirements or need further assistance with Advanced Dynamic Message Content, [create a support case](https://help.salesforce.com/s/articleView?language=en_US&id=sf.workcom_contact_support.htm&type=5&_ga=2.21226995.990954368.1679247489-1261322914.1674192271).

To know more about using ADMC in your campaigns, see [Use Advanced Dynamic Message Content](https://developer.salesforce.com/docs/marketing/personalization/guide/use-advanced-dynamic-message-content.md).

## See Also

- [Advanced Dynamic Message Content Cheatsheet](https://developer.salesforce.com/docs/marketing/personalization/guide/advanced-dynamic-message-content-cheatsheet.md)
- _Salesforce Help_: [Dynamic Message Content](https://help.salesforce.com/s/articleView?id=sf.mc_pers_mobile_campaign_dynamic_message_content.htm)
- _Salesforce Help_: [Open Time Email Campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_email_campaign.htm)

<!-- document id=14e086afbf86ce05d72638a31a65679bcf8e3e465dc013131f6ea9f5be8bfab3 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/advanced-use-case-apis.md -->

# Advanced Use-Case APIs

- [Marketing Cloud Personalization Trends](https://developer.salesforce.com/docs/marketing/personalization/guide/advanced-use-case-apis/is-trends.md)
- [Web Surveys](https://developer.salesforce.com/docs/marketing/personalization/guide/advanced-use-case-apis/web-surveys.md)

<!-- document id=bfb0ef60e87d87e794499adee82d040dfa90fbb34e0d86b0b5a4a3de2347d8f5 url=/developer/current/en-us/personalization/personalization/guides/custom-interface-template-configuration/arrays.md -->

# Arrays

Certain properties can be declared as an array, allowing the input to be multi-select. Doing so returns all selected values within an array.

| Property Type  | Supported As Array |
| -------------- | ------------------ |
| boolean        | No                 |
| string         | Yes                |
| number         | Yes                |
| Color          | No                 |
| Complex Object | Yes                |
| Select         | Yes                |
| Typed List     | No                 |

---

## Simple Types

Simple types can be put into multi-value arrays by simply making them arrays.

```typescript
    names: string[];
```

![Array Input](https://developer.salesforce.com/media/interface-template-configuration/ArrayInput.png)

String literal types can also be used as multi-value to provide the end user with a set of options of which multiple can be selected.

```typescript
    names: ("Alpha"|"Beta"|"Gamma"|"Delta")[];
```

![Array Select](https://developer.salesforce.com/media/interface-template-configuration/ArraySelect.png)

---

## Arrays of Complex Objects

Configurations can also be arrays of complex objects. You can use these arrays to permit the user to create a list of configured objects. When used in combination with the `@tabular` decorator, it is possible to create table structured inputs.

```typescript
export class LTVBands {
  label: string;
  minimumLtv: number;
}

export class LifecyclesLifecycle implements GearLifecycle {
  @tabular()
  valueBands: LTVBands[];
}
```

![Array Complex](https://developer.salesforce.com/media/interface-template-configuration/ArrayComplex.png)

<!-- document id=497dc74aca1b4c3f7aa77bd06b4dc6952fbf4b73fd56ec3a9d2311c7b9b13e51 url=/developer/current/en-us/personalization/personalization/guides/data-modeling/attributes.md -->

# Attributes

Attributes are custom-configured, type-safe fields that can store additional custom data at various levels in the platform. You can configure attributes for users, accounts, catalog objects, and profile objects.

## Supported Value Types

The following table details the value types supported by Attributes.

| Value Type | Description                                                                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| String     | Text information                                                                                                                                  |
| Integer    | Whole numbers                                                                                                                                     |
| Decimal    | Floating point numbers                                                                                                                            |
| Date       | Date and time, specifically the JavaScript [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object |
| Boolean    | `true` or `false`                                                                                                                                 |
| null       | Attribute present but without an object value                                                                                                     |

## Details

Attribute collections are keyed off the attribute name/id, as depicted in the following example.

```typescript
attributes: { [attributeName: string]: Attribute };
```

Each `Attribute` contains a `value` and optional `metadata` about the value.

```typescript
interface Attribute {
  readonly value: AttributeValue;
  readonly metadata?: Readonly<ValueMetadata>;
}
```

A value can be of type `string`, `number`, `boolean`, `null`, `Date`, or a (potentially nested) collection containing them.

```typescript
type AttributeValue = string | number | boolean | Date | null | AttributeValueArray;

interface AttributeValueArray extends ReadonlyArray<AttributeValue> {}
```

The optional `metadata` can contain detailed information about the value, as depicted in the following example.

```typescript
/**
 * Source: https://github.com/usnistgov/NISTIR-8112/
 *
 * Glossary:
 *
 * Attribute Provider (AP) Manages and provides assertions of identity attributes to other relying and federated
 * parties.
 *
 * Relying Party (RP) An entity that relies upon a subject’s authenticator(s) and credentials or an IDP's assertion of a
 * subject’s identity, typically to process a transaction or to grant access to information or a system. In this case,
 * the RP is the Personalization app.
 */
interface ValueMetadata {
  /**
   * The name of the entity that issues or creates the initial attribute value.
   *
   * The Origin element conveys the name of the entity that established the initial attribute value. This may or
   * may not be an authoritative entity, or the provider; if, for example, the AP generates the attribute value
   * through a derivation process, then the AP would be the origin. The key distinction between the origin and the
   * provider is the act of initially generating, capturing, or provisioning the attribute's value, rather than
   * just asserting the attribute's value to an RP.
   *
   * e.g. CRM, PointOfSaleSystem, FulfillmentSystem, or LoyaltySystem
   */
  origin?: string;
  /**
   * The name of the entity that is providing the attribute.
   *
   * This specifies the name of the entity that supplies the attribute value to the RP. This does not have to be
   * the AP itself. This element enables RPs to understand and evaluate the source of the individual attribute
   * values that may be included in a bundle of attributes. For example, if a full service credential provider
   * generates an assertion with several identity attributes provided by multiple APs, the {@code provider}
   * element enables the RP to understand, at a granular level, where each has come from and determine whether or
   * not that value can be used for access to specific resources. In instances where a single attribute is
   * asserted directly to the RP, this element may be omitted since the assertion itself will carry the provider
   * information as well as a certificate or digital signature.
   *
   * e.g. CsvUserEtlJob:user-20190528.csv.gz
   */
  provider?: string;
  /**
   * the ID of the Personalization gear that updated the attribute, or null if it was not updated by a gear
   */
  gearId?: string;
  /**
   * The date and time when the attribute value was last updated
   */
  lastUpdated?: Date;
  /**
   * The date and time when the attribute value was last verified as being true and belonging to the specified
   * individual
   */
  lastVerified?: Date;
  /**
   * Metadata relevant or pertaining to the security classification of a given attribute's value
   */
  classification?: Classification;
}

type Classification = "Sensitive" | "PersonallyIdentifiable" | "NonSensitive";
```

**important:** The `publishedDate` attribute must be exclusively used for articles and blogs. For other use cases, create a new custom attribute.

## Immutability

Attribute TypeScript declarations can almost always contain a `read-only` modifier. Attribute collections are mutable, which means you can add, replace, and remove attributes. However, each attribute is immutable after it is created, ensuring that an attribute value and its optional associated metadata remain in sync. This immutability also means that you must define a value and its optional associated metadata together. Currently, you cannot replace or remove an entire collection of attributes. Instead, you can mutate the existing collection.

## Example Usages

### Creating Attributes

```typescript
function mutatingUserAttributes(user: User): void {
  // Removing
  delete user.attributes.nameToDelete;
  delete user.attributes["bracketStyle"];

  // Adding
  user.attributes.someString = { value: "hi" };
  user.attributes["someInt"] = {
    value: 123,
    metadata: { lastUpdated: new Date(), classification: "NonSensitive" },
  };
  user.attributes.someDecimal = { value: 123.45 };
  user.attributes["someDate"] = { value: new Date(322376400000) };
  user.attributes.someBool = { value: false };
  user.attributes.someArray = { value: ["one", 2, null, new Date()] };

  // Building up complex array to add
  val = [];
  val.push("Abigail");
  val.push({ cell: "555-1234" });
  val.push([2, 4, 6]);
  val.push({ a: ["b"], c: { d: ["e", ["f"]] } });
  val.push([{ one: 2, three: { four: [5, [6, 7]] } }, [8, { nine: 10 }]]);
  meta = {};
  meta.origin = "someOrigin";
  meta.lastUpdated = new Date();
  user.attributes.complexArray = { value: val, metadata: meta };
}
```

### Reading Attributes

```typescript
// Not fully safe examples:
function readingUserAttributeValuesUnsafely(user: User): void {
  // Assuming attribute present and correct value type, simply casting:
  let str: string = user.attributes.someString.value as string;

  // Checking attribute present, then assuming correct value type and casting.
  // Using undefined to represent not-present:
  let num: number | undefined = !user.attributes.someNum
    ? undefined
    : (user.attributes.someNum.value as number);
}

// Fully safe examples:
function readingUserAttributeValuesSafely(user: User): void {
  // Handling all cases:
  if (!user.attributes.someString) {
    // Attribute not present
  } else if (user.attributes.someString.value === null) {
    // Attribute value null
  } else if (typeof user.attributes.someString.value !== "string") {
    // Attribute value not a string
  } else {
    const str: string = user.attributes.someString.value as string;
  }

  // Checking attribute present and value type.
  // Using undefined to represent not-present or undesired-type:
  let bool: boolean | undefined =
    user.attributes.someBool && typeof user.attributes.someBool.value === "boolean"
      ? (user.attributes.someBool.value as boolean)
      : undefined;

  // Similar but as an if statement:
  if (user.attributes.someBool && typeof user.attributes.someBool.value === "boolean") {
    const bool: boolean = user.attributes.someBool.value as boolean;
  }

  // Similar but using guard functions:

  if (user.attributes.someBool && isBoolean(user.attributes.someBool.value)) {
    const bool: boolean = user.attributes.someBool.value;
  }

  if (user.attributes.someDate && isDate(user.attributes.someDate.value)) {
    const date: Date = user.attributes.someDate.value;
  }

  if (user.attributes.complexArray && isArray(user.attributes.complexArray.value)) {
    const arr: AttributeValueArray = user.attributes.complexArray.value;
    if (arr.length > 0 && isNumber(arr[0])) {
      const num: number = arr[0] as number;
    }
  }
}

// Guard functions:

// Currently the platform may provide a Date-like proxy, with getTime() etc. So avoid `instanceof`.
function isDate(value: AttributeValue): value is Date {
  return typeof value === "object" && typeof (value as Date).getTime === "function";
}

function isArray(value: AttributeValue): value is AttributeValueArray {
  return Array.isArray(value);
}

function isBoolean(value: AttributeValue): value is boolean {
  return typeof value === "boolean";
}

function isString(value: AttributeValue): value is string {
  return typeof value === "string";
}

function isNumber(value: AttributeValue): value is number {
  return typeof value === "number";
}

function isNull(value: AttributeValue): value is null {
  return value === null;
}
```

<!-- document id=ba93acd4dd9e814828a10f60ad4962c5f3f86d7674759ac5b560fd3487291d0b url=/developer/current/en-us/personalization/personalization/guides/additional-apis/audit-log-api.md -->

# Audit Log API

The Marketing Cloud Personalization Audit Log API enables you to programmatically retrieve access and activity logs from your Personalization instance. You can use the Audit Log API to retrieve logs for specific date ranges up to 50 days in the past. This API provides paginated responses with up to 2000 records per page. Each log record includes information about authentication, API token and user management, campaigns, templates, catalog configurations, segments, and other related events.

You can use these logs for security and investigation purposes, and to demonstrate compliance with laws, regulations, and policies. In addition, using a specified timeframe, the API enables you to export audit trail information into your internal systems for easy storage, search, and analysis.

## Method and Endpoint

`GET` `/api/audit/list`

## Request URL

`https://<accountName>.<instance>.evergage.com/api/audit/list`

### URL Parameters

| URL Parameter | Required? | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountName` | Yes       | The Personalization account name. You can find the `accountName` by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the account name is `demo`.                                                                                                                                                                                                                                                          |
| `instance`    | Yes       | The Personalization instance identifier. You can find this value by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the instance identifier is `us-1`.                                                                                                                                                                                                                                                   |
| `page`        | No        | The specific page of data to return from a paginated response. The `page` parameter is typically used in conjunction with the `pageSize` parameter to control the number of records returned per page. The default value is `1`. To iterate through an entire response, start by setting page to `1`, and continue making requests until you get zero results.                                                                                                                                           |
| `pageSize`    | No        | The number of records to be returned per page in a paginated response. The `pageSize` parameter is typically used in conjunction with the `page` parameter to navigate through a paginated response. The default value is `100`.                                                                                                                                                                                                                                                                         |
| `startDate`   | No        | The start date of the date range for the audit logs to be returned. If unspecified, the default value is seven days before the current date. The `startDate` must precede the `endDate` and be sent as a string represented in the ISO-8601 format, for example, `2023-03-01T22:00:00.000Z`.                                                                                                                                                                                                             |
| `endDate`     | No        | The end date of the audit log date range that you want to retrieve. If unspecified, the default value is the current date. The `endDate` value must follow the `startDate` value, and be sent as a string represented in the ISO-8601 format, for example,`2023-03-01T22:00:00.000Z`. **Note**: You can retrieve logs for a maximum range of 50 days. If the range specified exceeds 50 days, the platform automatically adjusts the range and outputs logs from 50 days before the specified `endDate`. |

## Response Content Type

- `application/json`

## Authorization

`Authorization: Basic <base64-encoded-API-token>`

The Audit Log API uses API tokens to authenticate requests. Your API token must be a strict Base64 encoding of your API Key ID and its API Secret Key, separated by a colon. For the API token to have access to the Audit Log API, you must enable the **Can access Audit logs** permission when creating or updating a token. For security purposes, we recommend using a dedicated token to access Audit Log API with only this permission enabled.

**important:** A token with the **Can access Audit logs** permission doesn’t use dataset restrictions for the Audit Log data. Instead, the token provides access to Audit Log data across all datasets.

For more information on API tokens, see [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm) on Salesforce Help.

When using [cURL](https://curl.se/docs/manpage.html) to interact with the API, you can use the `-u "apiKeyId:apiKeySecret"` command-line option to send your API Key ID and API Key Secret. cURL automatically converts the `apiKeyId:apiKeySecret` pair into a Base64-encoded string and adds `Authorization: Basic <base64-encoded-API-token>` to the request header.

## Example Request

The following is an example API request sent using cURL.

```bash
curl -H 'Content-Type: application/json' \
     -u "<apiKeyId>:<apiKeySecret>" \
     "https://<accountName>.<instance>.evergage.com/api/audit/list?page=1&pageSize=50&startDate=2023-03-01T00:00:00.000Z&endDate=2023-03-10T00:00:00.000Z"
```

## Example Response

```json
{
    "page": 1,
    "pageSize": 9,
    "count": 706,
    "startDate": "2023-03-10T00:00:00.000Z",
    "endDate": "2023-03-23T00:00:00.000Z"
    "items": [
        {
            "date": "2023-03-22T13:01:54.451Z",
            "tenantId": "my_tenant_id",
            "employee": {
                "ipAddress": "2.2.2.2"
            },
            "type": "Authentication",
            "operation": {
                "name": "Auth",
                "detail": [
                    "LoginSuccess"
                ]
            },
            "object": {
                "id": "test@salesforce.com"
            }
        },
        {
            "date": "2023-03-22T12:01:52.917Z",
            "tenantId": "my_tenant_id",
            "datasetId": "my_dataset_id",
            "employee": {
                "id": "test@salesforce.com",
                "emailAddress": "test@salesforce.com"
            },
            "type": "Campaign Template",
            "operation": {
                "name": "Update",
                "detail": [
                    "draft-serverSideTypeScript"
                ]
            },
            "object": {
                "id": "TFz6G"
            }
        },
        {
            "date": "2023-03-22T11:46:28.255Z",
            "tenantId": "my_tenant_id",
            "datasetId": "my_dataset_id",
            "employee": {
                "id": "test@salesforce.com",
                "emailAddress": "test@salesforce.com"
            },
            "type": "Campaign Template",
            "operation": {
                "name": "Create"
            },
            "object": {
                "id": "TFz6G"
            }
        },
        {
            "date": "2023-03-22T11:12:30.821Z",
            "tenantId": "my_tenant_id",
            "datasetId": "my_dataset_id",
            "employee": {
                "id": "test@salesforce.com",
                "emailAddress": "test@salesforce.com"
            },
            "type": "Segment",
            "operation": {
                "name": "Update"
            },
            "object": {
                "id": "EBljH"
            }
        },
        {
            "date": "2023-03-22T11:12:04.440Z",
            "tenantId": "my_tenant_id",
            "datasetId": "my_dataset_id",
            "employee": {
                "id": "test@salesforce.com",
                "emailAddress": "test@salesforce.com"
            },
            "type": "Segment",
            "operation": {
                "name": "Create"
            },
            "object": {
                "id": "EBljH"
            }
        },
        {
            "date": "2023-03-22T11:09:57.150Z",
            "tenantId": "my_tenant_id",
            "datasetId": "my_dataset_id",
            "employee": {
                "id": "test@salesforce.com",
                "emailAddress": "test@salesforce.com"
            },
            "type": "Segment",
            "operation": {
                "name": "Update"
            },
            "object": {
                "id": "1zDIZ"
            }
        }
    ]
}
```

| Property                       | Optional | Data Type | Description                                                                                                                                                                                          |
| ------------------------------ | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page`                         | No       | Number    | The requested page number. The value of the `page` query parameter you specified in the request, or the default value if no page number was specified.                                               |
| `pageSize`                     | No       | Number    | The requested page size. The value of the `pageSize` query parameter you specified in the request, or the default value if no page number was specified.                                             |
| `count`                        | No       | Number    | Number of records for the specified date range.                                                                                                                                                      |
| `startDate`                    | No       | String    | The start date in the ISO-8601 format used when filtering the results. For example: `2023-03-01T22:00:00.000Z`.                                                                                      |
| `endDate`                      | No       | String    | The end date in the ISO-8601 format used when filtering the results. For example: `2023-03-01T22:00:00.000Z`.                                                                                        |
| `items`                        | No       | Array     | An array of Audit Log events.                                                                                                                                                                        |
| `<Item>.date`                  | No       | String    | The event date for a record in the ISO-8601 format. For example: 2023-03-01T22:00:00.000Z.A string representation of the event date in the ISO-8601 format. For example: `2023-03-01T22:00:00.000Z`. |
| `<Item>.tenantId`              | No       | String    | Your Personalization `accountName`.                                                                                                                                                                  |
| `<Item>.datasetId`             | Yes      | String    | The dataset where an event occurred. This property doesn’t exist for global events like authentication.                                                                                              |
| `<Item>.employee.ipAddress`    | Yes      | String    | The IP address of the user associated with the audit event, if available.                                                                                                                            |
| `<Item>.employee.id`           | Yes      | String    | The Marketing Cloud user ID associated with the audit event, if available.                                                                                                                           |
| `<Item>.employee.emailAddress` | Yes      | String    | The Marketing Cloud user email address associated with the audit event, if available.                                                                                                                |
| `<Item>.type`                  | No       | String    | Audit Log event type. For example: `API Token`, `Authentication`, `Segment`, `Campaign`, and so on.                                                                                                  |
| `<Item>.operation.name`        | No       | String    | The type of operation performed. Examples of available options: `Create`, `Read`, `Update`, `Delete`, `Auth`, `Execute`, `TestExecute`.                                                              |
| `<Item>.operation.detail`      | Yes      | Array     | A list of optional additional details about the operation performed by the user.                                                                                                                     |
| `<Item>.object.id`             | Yes      | String    | A reference to the object that was affected by the logged operation.                                                                                                                                 |

## See Also

- _Salesforce Help_: [View the Personalization Audit Log](https://help.salesforce.com/s/articleView?id=sf.mc_pers_audit_log_viewing.htm)
- _Salesforce Help_: [Personalization API Tokens](https://help.salesforce.com/s/articleView?language=en_US&id=sf.mc_pers_api_tokens.htm)

<!-- document id=bf27d6b6176496e4ba8904f3674086a48ccfe2697aa9bf733e85d61d154bbe53 url=/developer/current/en-us/personalization/personalization/guides/web-integration/example-sitemaps/b2b.md -->

# B2B

Using [Tableau](https://www.tableau.com) as our "client", the following document describes and presents code for an example implementation. The sample code in this document is not exhaustive and maps only key areas of the site that are valuable for demonstration purposes. The primary focus is depicting how to approach designing a Catalog for B2B websites. While each implementation is unique, this sitemap contends with many issues, particularly mapping B2B sites and websites without purchasable products in general.

**important:** The sitemap code examples in this article are only for demonstration purposes. Avoid copying sample code into your Sitemap Editor as it is built around example scenarios that can differ from your implementation's goals and use cases.

## Client Requirements

This section outlines the functionality that our imaginary client requires from their implementation. Since each client or customer always has a unique set of requirements and use cases in mind for Marketing Cloud Personalization, experience is the real teacher when it comes to knowing what questions to ask clients to help them establish their goals and requirements for their use of Personalization.

### Primary Goal

- Understand the content a user is most interested in based on their prior interactions with the site.

### Home page type

- Recommend Blogs similar to recently viewed Blogs, fallback to promote trending Blogs.

### Solutions, Learning, and Product Landing page types

- Recommend Articles of the same Category (solutions, learn, or products) as the currently viewed landing page.
- Personalize banner based on past interest in Articles under the currently viewed Category

### Solutions, Learning, and Product page types

- Capture `Industry`, `JobRole`, `PageBundle`, and `Department` values as related catalog objects.

### Product page type

- Capture `Keyword` values as a related catalog object.
- Recommend related product Articles by `Keyword`.
- Distinguish between `Add-On` and `Software` products in the Catalog.

### Blog Landing page type

- Recommend trending `Blogs`.

### Blog page type

- Recommend related `Blog` posts based on category.

## Discovery

- Since it is the only identity consistently available on the web and used as a username when users log in to the site, `emailAddress` is used as the default Web SDK identity attribute used for this implementation. The site already uses email addresses to identify its users, so we are configuring Personalization to piggyback on that identity attribute.
  > _**Aside**: Since an email address is Personally Identifiable Information (PII), make sure you have the appropriate approval from within your organization before using it as a Personalization Identity. Additionally, using emails captured from web forms, other than a login form, as an Identity could potentially cause privacy issues where more than one user is tied to a Personalization user. In the following code, email is only being captured from the login form when a user successfully logs in. The code capturing user id is designed to work on [Tableau Public](https://public.tableau.com/) as this portion of the Tableau site is accessible by everyone with a free public account. For more information on Identity, read [Identity System Setup for the Web SDK](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity_web_sdk.htm)._
- While this site does promote products, there is no ability to purchase products or attribute revenue to them from other channels, matching with user activity from the web. Since we do not need the special capabilities of the `Product` item type for this implementation, we are instead using the `Article` item type, using `Category` to tell types of `Article` items apart.
  > _**Aside**: If the website had a more robust, hierarchical category system in which it could be possible to share `Category` information between the `Article` types, we would instead configure a catalog object specifically to house the type of `Article`, such as `ArticleType`. This way, if solutions and products shared `Category` data, they would be relatable to each other, instead of belonging to siloed `Category` hierarchies, each starting with their respective `Article` type (solutions, products, and learning)._
- There is a categorization system already natively built into the site's blog section, so our code scrapes the categories already present in the `dataLayer` as `Category` in the Personalization Catalog. Collecting `Category` data for the `Blogs` help build user affinity based on those categories. These categories are used to also power the customer's use case to recommend related `Blogs` on blog pages based on the currently viewed `Category`.
- In addition to `Category` data, the `dataLayer` contains other useful information, such as `Department` and `Job Role`. The values for `Department` and `Job Role` are collected as `relatedCatalogObjects` to tie them to each of the collected `Article` types. As these values are collected, they are used to build a user's affinity towards them, which can then be used for segmentation and potentially for recommending `Articles` of any `Category` based on one of these related catalog objects, instead of only recommending `Articles` of one type at a time.
- To distinguish between `Add-On` and `Software` products in the Catalog, as stated in the "Client Requirements", we are mapping a related catalog object called `ProductType` on the "product" page type. Remember, we are using the `Article` item type to house Catalog data for the `product`, `solutions`, and `learning` page types. As a result, our `ProductType` catalog object is attached to the `Article` Catalog item type when configuring the Catalog, even though it is mapped only on one page type containing `Article` Catalog data. The `ProductType` related catalog object helps to more granularly distinguish which type of product `Article` is being viewed by the user and create highly targeted recipes based on that activity, if desired.

**note:** The following examples assume that `emailAddress` has been configured as the default Web SDK Identity.

## Example Sitemap in the SalesforceInteractions Namespace

```javascript
SalesforceInteractions.init({
  cookieDomain: "tableau.com",
  consents: [
    {
      purpose: SalesforceInteractions.mcis.ConsentPurpose.Personalization,
      provider: "Example Consent Manager",
      status: SalesforceInteractions.ConsentStatus.OptIn,
    },
  ],
}).then(() => {
  const findInDataLayer = (targetAttribute) => {
    if (!window.dataLayer) {
      return;
    }
    for (let i = 0; i < window.dataLayer.length; i++) {
      const result = SalesforceInteractions.mcis.getValueFromNestedObject(
        "window.dataLayer[" + i + "]",
      );
      if (result && result[targetAttribute]) {
        return result;
      }
    }
    return;
  };

  // We set a value for this variable only once per page load and then reference it several times for the data found in the dataLayer needed for each page.
  let pageDetails;
  const setPageDetailsFromDataLayer = () => {
    pageDetails = pageDetails || findInDataLayer("entityId");
  };

  /*
    Here we will first check session storage for the islogin item containing the user's email that is associated with
    their account. This value is set in the global event listener in the site config when a submission event occurs. On this
    website, both successful and invalid form submissions emit a submission event, the page also is quickly reloaded
    after a successful login.
    In this unusual situation, we will first save the submitted data in session storage. Then when the page loads,
    we check for the islogin value in session storage and then look for a DOM element which indicates a successful
    login before retrieving the stored user email and sending our login event.
    */
  let loginEvent = sessionStorage.getItem("islogin");
  // if there is a stored login event...
  if (loginEvent) {
    // wait for the logged in user dropdown to appear in the nav, signifying a successful login
    SalesforceInteractions.DisplayUtils.pageElementLoaded(
      "#block-public-sitewide-ui-author-profile-dropdown",
    ).then(() => {
      // remove the stored email from session storage
      sessionStorage.removeItem("islogin");
      // construct and send the Login Success event to Personalization
      SalesforceInteractions.sendEvent({
        interaction: { name: "Login Success" },
        user: {
          /*
                        The users email address provided in the login form is sent to Personalization as user.identities.emailAddress because
                        in this example, emailAddress is configured to be the default identity for the web channel.
                    */
          identities: {
            emailAddress: loginEvent,
          },
        },
      });
    });
  }

  const config = {
    global: {
      contentZones: [
        { name: "global_popup" },
        { name: "global_infobar" },
        { name: "global_exit_intent" },
        /*
                Since the website does not have consistent selectors and structure within the Article pages,
                this content zone will be used to add recs to the bottom of Article pages.
                */
        { name: "global_footer", selector: "footer.global-footer" },
      ],
      listeners: [
        /*
                Here we are listening for all submission events that happen within this document. This pattern
                can be used to create generic form submission event handlers, or even just to consolidate them
                to one place in the sitemap code.
                */
        SalesforceInteractions.listener("submit", "body", (event) => {
          // Check the id of the event target to check for the login form we want to scrape data from
          if (event.target.id === "login-form") {
            // loop through login form fields...
            for (i = 0; i < event.target.length; i++) {
              // Find the email field by id within the event object.
              if (event.target[i].id === "login-email") {
                // save user email in session storage
                sessionStorage.setItem("islogin", event.target[i].value);
              }
            }
          }
        }),
      ],
    },
    pageTypeDefault: {
      name: "default",
      interaction: {
        name: "Default Page",
      },
    },
    pageTypes: [
      {
        name: "home",
        isMatch: () => /^\/$/.test(window.location.pathname),
        interaction: {
          name: "Homepage",
        },
        contentZones: [
          { name: "home_recs_1", selector: "section.datalocation-audience-segment-links" },
          { name: "home_recs_2", selector: "section.datalocation-customer-stories" },
        ],
      },
      {
        name: "products_landing",
        isMatch: () => /^\/products\/?$/.test(window.location.pathname),
        interaction: {
          name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
          catalogObject: {
            /*
                        Remember, Catalog IDs are case sensitive. Transforming collected values as all upper case or all lower
                        case is a common method for ensuring consistency throughout the site when creating Catalog IDs with the
                        sitemap which do not need to correspond to data in external systems.
                        */
            type: "Category",
            id: () =>
              SalesforceInteractions.mcis
                .getLastPathComponentWithoutExtension(window.location.pathname)
                .toLowerCase(),
            attributes: {
              url: SalesforceInteractions.resolvers.fromCanonical(),
              name: SalesforceInteractions.resolvers.fromMeta("og:title"),
            },
          },
        },
        contentZones: [{ name: "products_landing_hero_banner", selector: "#hero" }],
      },
      {
        name: "solutions_landing",
        isMatch: () =>
          /^\/solutions\/?(customers|industries|departments|technologies)?$/.test(
            window.location.pathname,
          ),
        interaction: {
          name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
          catalogObject: {
            /*
                        The last parameter of each resolver function accepts a function which returns whatever the desired final value is.
                        This is very useful when you need to transform or sanitize a scraped value before sending it to Interaction studio.

                        You can learn more about resolver functions here: https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.html#resolvers

                        Below, the pathname portion of the URL is transformed into a hierarchal Category id.
                        */
            type: "Category",
            id: SalesforceInteractions.resolvers.fromWindow("location.pathname", (path) =>
              path.split("/").slice(1).join("|").toLowerCase(),
            ),
            attributes: {
              url: SalesforceInteractions.resolvers.fromCanonical(),
              name: SalesforceInteractions.resolvers.fromMeta("og:title"),
            },
          },
        },
        contentZones: [{ name: "solutions_landing_hero_banner", selector: "#hero" }],
      },
      {
        name: "learning_landing",
        isMatch: () => /^\/learn\/?$/.test(window.location.pathname),
        interaction: {
          name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
          catalogObject: {
            type: "Category",
            id: () =>
              SalesforceInteractions.mcis
                .getLastPathComponentWithoutExtension(window.location.pathname)
                .toLowerCase(),
            attributes: {
              url: SalesforceInteractions.resolvers.fromCanonical(),
              name: SalesforceInteractions.resolvers.fromMeta("og:title"),
            },
          },
        },
        contentZones: [
          {
            name: "learning_landing_gray_recs",
            selector: ".entity-paragraphs-item.paragraph--type--cross-reference",
          },
          { name: "learning_landing_hero_banner", selector: "#hero" },
        ],
      },
      {
        name: "blog_landing",
        isMatch: () => /^\/about\/blog\/?$/.test(window.location.pathname),
        interaction: {
          name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
          catalogObject: {
            type: "Category",
            id: () =>
              SalesforceInteractions.mcis
                .getLastPathComponentWithoutExtension(window.location.pathname)
                .toLowerCase(),
            attributes: {
              url: SalesforceInteractions.resolvers.fromCanonical(),
              name: SalesforceInteractions.resolvers.fromMeta("og:title"),
            },
          },
        },
        contentZones: [
          { name: "blog_landing_card_wall", selector: ".card-wall" },
          { name: "blog_landing_hero_banner", selector: "#hero" },
        ],
      },
      {
        name: "product",
        action: "Product",
        isMatch: () => {
          if (/^\/products\//.test(window.location.pathname)) {
            /*
                        We only want to call setPageDetailsFromDataLayer() when pages which rely on scraping information from the dataLayer are actually matched.
                        Adding a conditional statement prevents this function from being called on every page on the site as Personalization resolves every
                        isMatch function to see which page type matches the current one.
                        */
            setPageDetailsFromDataLayer();
            return true;
          }
          return false;
        },
        interaction: {
          name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
          catalogObject: {
            /*
                        Remember, while this site does promote products, there is no ability to purchase products or attribute
                        revenue to them from other channels which would match with user activity from the web.
                        Since the special capabilities of the Product item type will not be needed for this implementation,
                        we will instead use the Article item type, utilizing Category to tell types of Article apart.
                        */
            type: "Article",
            /*
                        We are using SalesforceInteractions.mcis.getValueFromNestedObject() to more easily reference data from the pageDetails
                        object after the value is set when the page matches.
                        */
            id: () => SalesforceInteractions.mcis.getValueFromNestedObject("entityId", pageDetails),
            attributes: {
              name: () =>
                SalesforceInteractions.mcis.getValueFromNestedObject("entityLabel", pageDetails),
              url: SalesforceInteractions.resolvers.fromCanonical(),
              imageUrl: SalesforceInteractions.resolvers.fromSelectorAttribute(
                "div.feature-highlight__image img",
                "src",
              ),
            },
            relatedCatalogObjects: {
              Category: SalesforceInteractions.resolvers.fromWindow("location.pathname", (path) => {
                const categories = path.split("/").slice(1);
                categories.pop();
                if (categories.length === 0) {
                  const dataLayerCategories = SalesforceInteractions.mcis.getValueFromNestedObject(
                    "page.category1",
                    pageDetails,
                  );
                  return dataLayerCategories ? [dataLayerCategories.toLowerCase()] : [];
                }
                return [categories.join("|").toLowerCase()];
              }),
              ProductType: () =>
                window.location.pathname.indexOf("add-ons") > -1 ? ["Add-On"] : ["Software"],
              Industry: () =>
                SalesforceInteractions.mcis.getValueFromNestedObject(
                  "dataModelFields.field_dmo_industries",
                  pageDetails,
                ) || null,
              Department: () =>
                SalesforceInteractions.mcis.getValueFromNestedObject(
                  "dataModelFields.field_departments",
                  pageDetails,
                ) || null,
              JobRole: () =>
                SalesforceInteractions.mcis.getValueFromNestedObject(
                  "dataModelFields.taxonomy_vocabulary_23",
                  pageDetails,
                ) || null,
              PageBundle: () => {
                const pageBundle = SalesforceInteractions.mcis.getValueFromNestedObject(
                  "entityBundleNice",
                  pageDetails,
                );
                return pageBundle ? [pageBundle] : null;
              },
              Keyword: SalesforceInteractions.resolvers.fromMeta("keywords", (ele) => {
                return ele ? ele.split(/\,\s*/) : null;
              }),
            },
          },
        },
        listeners: [
          SalesforceInteractions.listener(
            "submit",
            "#webform-submission-email-embeddable-1-add-form",
            (event) => {
              SalesforceInteractions.sendEvent({
                interaction: { name: "Free Trial Download" },
                /*
                            A content zone is provided in this event in order to allow a campaign targeting the "global_infobar"
                            content zone to be returned in the response sent back from Personalization with this request.
                            */
                source: {
                  contentZones: ["global_infobar"],
                },
              });
            },
          ),
        ],
      },
      {
        name: "solutions",
        isMatch: () => {
          if (
            /\/solutions\/(?!customers|industries|departments|technologies)/.test(
              window.location.pathname,
            )
          ) {
            setPageDetailsFromDataLayer();
            return true;
          }
          return false;
        },
        interaction: {
          name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
          catalogObject: {
            type: "Article",
            id: () => SalesforceInteractions.mcis.getValueFromNestedObject("entityId", pageDetails),
            attributes: {
              name: () =>
                SalesforceInteractions.mcis.getValueFromNestedObject("entityLabel", pageDetails),
              url: SalesforceInteractions.resolvers.fromCanonical(),
              imageUrl: SalesforceInteractions.resolvers.fromSelectorAttribute(
                "div.feature-highlight__image img",
                "src",
              ),
            },
            relatedCatalogObjects: {
              Category: SalesforceInteractions.resolvers.fromWindow("location.pathname", (path) => {
                const categories = path.split("/").slice(1);
                categories.pop();
                return [categories.join("|").toLowerCase()];
              }),
              Industry: () =>
                SalesforceInteractions.mcis.getValueFromNestedObject(
                  "dataModelFields.field_dmo_industries",
                  pageDetails,
                ) || null,
              Department: () =>
                SalesforceInteractions.mcis.getValueFromNestedObject(
                  "dataModelFields.field_departments",
                  pageDetails,
                ) || null,
              JobRole: () =>
                SalesforceInteractions.mcis.getValueFromNestedObject(
                  "dataModelFields.taxonomy_vocabulary_23",
                  pageDetails,
                ) || null,
              PageBundle: () => {
                const pageBundle = SalesforceInteractions.mcis.getValueFromNestedObject(
                  "entityBundleNice",
                  pageDetails,
                );
                return pageBundle ? [pageBundle] : null;
              },
            },
          },
        },
      },
      {
        name: "learning",
        isMatch: () => {
          if (/^\/learn\//.test(window.location.pathname)) {
            setPageDetailsFromDataLayer();
            return true;
          }
          return false;
        },
        interaction: {
          name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
          catalogObject: {
            type: "Article",
            id: () => SalesforceInteractions.mcis.getValueFromNestedObject("entityId", pageDetails),
            attributes: {
              name: () =>
                SalesforceInteractions.mcis.getValueFromNestedObject("entityLabel", pageDetails),
              url: SalesforceInteractions.resolvers.fromCanonical(),
              imageUrl: SalesforceInteractions.resolvers.fromSelectorAttribute(
                "div.feature-highlight__image img",
                "src",
              ),
            },
            relatedCatalogObjects: {
              Category: SalesforceInteractions.resolvers.fromWindow("location.pathname", (path) => {
                const categories = path.split("/").slice(1);
                categories.pop();
                return [categories.join("|").toLowerCase()];
              }),
              Industry: () =>
                SalesforceInteractions.mcis.getValueFromNestedObject(
                  "dataModelFields.field_dmo_industries",
                  pageDetails,
                ) || null,
              Department: () =>
                SalesforceInteractions.mcis.getValueFromNestedObject(
                  "dataModelFields.field_departments",
                  pageDetails,
                ) || null,
              JobRole: () =>
                SalesforceInteractions.mcis.getValueFromNestedObject(
                  "dataModelFields.taxonomy_vocabulary_23",
                  pageDetails,
                ) || null,
              PageBundle: () => {
                const pageBundle = SalesforceInteractions.mcis.getValueFromNestedObject(
                  "entityBundleNice",
                  pageDetails,
                );
                return pageBundle ? [pageBundle] : null;
              },
            },
          },
        },
      },
      {
        name: "blog",
        isMatch: () => {
          if (/\/about\/blog\/\d+\/\d+\/.+/.test(window.location.pathname)) {
            setPageDetailsFromDataLayer();
            return true;
          }
          return false;
        },
        interaction: {
          name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
          catalogObject: {
            type: "Blog",
            id: () => SalesforceInteractions.mcis.getValueFromNestedObject("entityId", pageDetails),
            attributes: {
              name: () =>
                SalesforceInteractions.mcis.getValueFromNestedObject("entityLabel", pageDetails),
              url: SalesforceInteractions.resolvers.fromCanonical(),
              imageUrl: SalesforceInteractions.resolvers.fromMeta("og:image"),
            },
            relatedCatalogObjects: {
              Category: () => [
                SalesforceInteractions.mcis.getValueFromNestedObject(
                  "flatTaxonomy.blog_categories",
                  pageDetails,
                ),
              ],
            },
          },
        },
        listeners: [
          SalesforceInteractions.listener("submit", ".premium-access-ajax", () => {
            const eloquaId = findInDataLayer("EloquaGuid");
            if (eloquaId) {
              SalesforceInteractions.sendEvent({
                interaction: { name: "Tableau Blog Sign-up" },
                user: { attributes: { eloquaId: eloquaId } },
              });
            }
          }),
        ],
        contentZones: [
          /*
                    As in this case below, content zones do not necessarily have to denote content to be replaced, they can be
                    useful for inserting template content before or after the the DOM node with the provided selector.
                    */
          { name: "blog_text_content", selector: ".field--name-field-page-sections" },
        ],
      },
    ],
  };
  SalesforceInteractions.initSitemap(config);
});
```

## Example Sitemap in the Evergage Namespace

```javascript
Evergage.init({
  cookieDomain: "tableau.com",
}).then(() => {
  const findInDataLayer = (targetAttribute) => {
    if (!window.dataLayer) {
      return;
    }
    for (let i = 0; i < window.dataLayer.length; i++) {
      const result = Evergage.util.getValueFromNestedObject("window.dataLayer[" + i + "]");
      if (result && result[targetAttribute]) {
        return result;
      }
    }
    return;
  };

  // We set a value for this variable only once per page load and then reference it several times for the data found in the dataLayer needed for each page.
  let pageDetails;
  const setPageDetailsFromDataLayer = () => {
    pageDetails = pageDetails || findInDataLayer("entityId");
  };

  /*
    Here we will first check session storage for the islogin item containing the user's email that is associated with
    their account. This value is set in the global event listener in the site config when a submission event occurs. On this
    website, both successful and invalid form submissions emit a submission event, the page also is quickly reloaded
    after a successful login.
    In this unusual situation, we will first save the submitted data in session storage. Then when the page loads,
    we check for the islogin value in session storage and then look for a DOM element which indicates a successful
    login before retrieving the stored user email and sending our login event.
    */
  let loginEvent = sessionStorage.getItem("islogin");
  // if there is a stored login event...
  if (loginEvent) {
    // wait for the logged in user dropdown to appear in the nav, signifying a successful login
    Evergage.DisplayUtils.pageElementLoaded(
      "#block-public-sitewide-ui-author-profile-dropdown",
    ).then(() => {
      // remove the stored email from session storage
      sessionStorage.removeItem("islogin");
      // construct and send the Login Success event to Personalization
      Evergage.sendEvent({
        action: "Login Success",
        user: {
          /*
                        The users email address provided in the login form is sent to Personalization as user.id because
                        in this example, emailAddress is configured to be the default identity for the web channel.
                        */
          id: loginEvent,
        },
      });
    });
  }

  const config = {
    global: {
      contentZones: [
        { name: "global_popup" },
        { name: "global_infobar" },
        { name: "global_exit_intent" },
        /*
                Since the website does not have consistent selectors and structure within the Article pages,
                this content zone will be used to add recs to the bottom of Article pages.
                */
        { name: "global_footer", selector: "footer.global-footer" },
      ],
      listeners: [
        /*
                Here we are listening for all submission events that happen within this document. This pattern
                can be used to create generic form submission event handlers, or even just to consolidate them
                to one place in the sitemap code.
                */
        Evergage.listener("submit", document, (event) => {
          // Check the id of the event target to check for the login form we want to scrape data from
          if (event.target.id === "login-form") {
            // loop through login form fields...
            for (i = 0; i < event.target.length; i++) {
              // Find the email field by id within the event object.
              if (event.target[i].id === "login-email") {
                // save user email in session storage
                sessionStorage.setItem("islogin", event.target[i].value);
              }
            }
          }
        }),
      ],
    },
    pageTypeDefault: {
      name: "default",
    },
    pageTypes: [
      {
        name: "home",
        action: "Homepage",
        isMatch: () => /^\/$/.test(window.location.pathname),
        contentZones: [
          { name: "home_recs_1", selector: "section.datalocation-audience-segment-links" },
          { name: "home_recs_2", selector: "section.datalocation-customer-stories" },
        ],
      },
      {
        name: "products_landing",
        action: "Products Landing",
        isMatch: () => /^\/products\/?$/.test(window.location.pathname),
        catalog: {
          Category: {
            /*
                        Remember, Catalog IDs are case sensitive. Transforming collected values as all upper case or all lower
                        case is a common method for ensuring consistency throughout the site when creating Catalog IDs with the
                        sitemap which do not need to correspond to data in external systems.
                        */
            _id: () =>
              Evergage.util
                .getLastPathComponentWithoutExtension(window.location.pathname)
                .toLowerCase(),
            url: Evergage.resolvers.fromCanonical(),
            name: Evergage.resolvers.fromMeta("og:title"),
          },
        },
        contentZones: [{ name: "products_landing_hero_banner", selector: "#hero" }],
      },
      {
        name: "solutions_landing",
        action: "Solutions Landing",
        isMatch: () =>
          /^\/solutions\/?(customers|industries|departments|technologies)?$/.test(
            window.location.pathname,
          ),
        catalog: {
          Category: {
            /*
                        The last parameter of each resolver function accepts a function which returns whatever the desired final value is.
                        This is very useful when you need to transform or sanitize a scraped value before sending it to Interaction studio.

                        You can learn more about resolver functions here: https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.html#resolvers

                        Below, the pathname portion of the URL is transformed into a hierarchal Category id.
                        */
            _id: Evergage.resolvers.fromWindow("location.pathname", (path) =>
              path.split("/").slice(1).join("|").toLowerCase(),
            ),
            url: Evergage.resolvers.fromCanonical(),
            name: Evergage.resolvers.fromMeta("og:title"),
          },
        },
        contentZones: [{ name: "solutions_landing_hero_banner", selector: "#hero" }],
      },
      {
        name: "learning_landing",
        action: "Learning Landing",
        isMatch: () => /^\/learn\/?$/.test(window.location.pathname),
        catalog: {
          Category: {
            _id: () =>
              Evergage.util
                .getLastPathComponentWithoutExtension(window.location.pathname)
                .toLowerCase(),
            url: Evergage.resolvers.fromCanonical(),
            name: Evergage.resolvers.fromMeta("og:title"),
          },
        },
        contentZones: [
          {
            name: "learning_landing_gray_recs",
            selector: ".entity-paragraphs-item.paragraph--type--cross-reference",
          },
          { name: "learning_landing_hero_banner", selector: "#hero" },
        ],
      },
      {
        name: "blog_landing",
        action: "Blog Landing",
        isMatch: () => /^\/about\/blog\/?$/.test(window.location.pathname),
        catalog: {
          Category: {
            _id: () =>
              Evergage.util
                .getLastPathComponentWithoutExtension(window.location.pathname)
                .toLowerCase(),
            url: Evergage.resolvers.fromCanonical(),
            name: Evergage.resolvers.fromMeta("og:title"),
          },
        },
        contentZones: [
          { name: "blog_landing_card_wall", selector: ".card-wall" },
          { name: "blog_landing_hero_banner", selector: "#hero" },
        ],
      },
      {
        name: "product",
        action: "Product",
        isMatch: () => {
          if (/^\/products\//.test(window.location.pathname)) {
            /*
                        We only want to call setPageDetailsFromDataLayer() when pages which rely on scraping information from the dataLayer are actually matched.
                        Adding a conditional statement prevents this function from being called on every page on the site as Personalization resolves every
                        isMatch function to see which page type matches the current one.
                        */
            setPageDetailsFromDataLayer();
            return true;
          }
          return false;
        },
        catalog: {
          /*
                    Remember, while this site does promote products, there is no ability to purchase products or attribute
                    revenue to them from other channels which would match with user activity from the web.
                    Since the special capabilities of the Product item type will not be needed for this implementation,
                    we will instead use the Article item type, utilizing Category to tell types of Article apart.
                    */
          Article: {
            /*
                        We are using Evergage.util.getValueFromNestedObject() to more easily reference data from the pageDetails
                        object after the value is set when the page matches.
                        */
            _id: () => Evergage.util.getValueFromNestedObject("entityId", pageDetails),
            name: () => Evergage.util.getValueFromNestedObject("entityLabel", pageDetails),
            url: Evergage.resolvers.fromCanonical(),
            imageUrl: Evergage.resolvers.fromSelectorAttribute(
              "div.feature-highlight__image img",
              "src",
            ),
            categories: Evergage.resolvers.fromWindow("location.pathname", (path) => {
              const categories = path.split("/").slice(1);
              categories.pop();
              if (categories.length === 0) {
                const dataLayerCategories = Evergage.util.getValueFromNestedObject(
                  "page.category1",
                  pageDetails,
                );
                return dataLayerCategories ? [dataLayerCategories.toLowerCase()] : [];
              }
              return [categories.join("|").toLowerCase()];
            }),
            relatedCatalogObjects: {
              // In case you're using 'dimensions' instead of 'relatedCatalogObjects', you can continue to do so as they both function the same way.
              ProductType: () =>
                window.location.pathname.indexOf("add-ons") > -1 ? ["Add-On"] : ["Software"],
              Industry: () =>
                Evergage.util.getValueFromNestedObject(
                  "dataModelFields.field_dmo_industries",
                  pageDetails,
                ) || null,
              Department: () =>
                Evergage.util.getValueFromNestedObject(
                  "dataModelFields.field_departments",
                  pageDetails,
                ) || null,
              JobRole: () =>
                Evergage.util.getValueFromNestedObject(
                  "dataModelFields.taxonomy_vocabulary_23",
                  pageDetails,
                ) || null,
              PageBundle: () => {
                const pageBundle = Evergage.util.getValueFromNestedObject(
                  "entityBundleNice",
                  pageDetails,
                );
                return pageBundle ? [pageBundle] : null;
              },
              Keyword: Evergage.resolvers.fromMeta("keywords", (ele) => {
                return ele ? ele.split(/\,\s*/) : null;
              }),
            },
          },
        },
        listeners: [
          Evergage.listener(
            "submit",
            "#webform-submission-email-embeddable-1-add-form",
            (event) => {
              Evergage.sendEvent({
                action: "Free Trial Download",
                /*
                            A content zone is provided in this event in order to allow a campaign targeting the "global_infobar"
                            content zone to be returned in the response sent back from Personalization with this request.
                            */
                source: {
                  contentZones: ["global_infobar"],
                },
              });
            },
          ),
        ],
      },
      {
        name: "solutions",
        action: "Solutions",
        isMatch: () => {
          if (
            /\/solutions\/(?!customers|industries|departments|technologies)/.test(
              window.location.pathname,
            )
          ) {
            setPageDetailsFromDataLayer();
            return true;
          }
          return false;
        },
        catalog: {
          Article: {
            _id: () => Evergage.util.getValueFromNestedObject("entityId", pageDetails),
            name: () => Evergage.util.getValueFromNestedObject("entityLabel", pageDetails),
            url: Evergage.resolvers.fromCanonical(),
            imageUrl: Evergage.resolvers.fromSelectorAttribute(
              "div.feature-highlight__image img",
              "src",
            ),
            categories: Evergage.resolvers.fromWindow("location.pathname", (path) => {
              const categories = path.split("/").slice(1);
              categories.pop();
              return [categories.join("|").toLowerCase()];
            }),
            relatedCatalogObjects: {
              Industry: () =>
                Evergage.util.getValueFromNestedObject(
                  "dataModelFields.field_dmo_industries",
                  pageDetails,
                ) || null,
              Department: () =>
                Evergage.util.getValueFromNestedObject(
                  "dataModelFields.field_departments",
                  pageDetails,
                ) || null,
              JobRole: () =>
                Evergage.util.getValueFromNestedObject(
                  "dataModelFields.taxonomy_vocabulary_23",
                  pageDetails,
                ) || null,
              PageBundle: () => {
                const pageBundle = Evergage.util.getValueFromNestedObject(
                  "entityBundleNice",
                  pageDetails,
                );
                return pageBundle ? [pageBundle] : null;
              },
            },
          },
        },
      },
      {
        name: "learning",
        action: "Learning",
        isMatch: () => {
          if (/^\/learn\//.test(window.location.pathname)) {
            setPageDetailsFromDataLayer();
            return true;
          }
          return false;
        },
        catalog: {
          Article: {
            _id: () => Evergage.util.getValueFromNestedObject("entityId", pageDetails),
            name: () => Evergage.util.getValueFromNestedObject("entityLabel", pageDetails),
            url: Evergage.resolvers.fromCanonical(),
            imageUrl: Evergage.resolvers.fromSelectorAttribute(
              "div.feature-highlight__image img",
              "src",
            ),
            categories: Evergage.resolvers.fromWindow("location.pathname", (path) => {
              const categories = path.split("/").slice(1);
              categories.pop();
              return [categories.join("|").toLowerCase()];
            }),
            relatedCatalogObjects: {
              Industry: () =>
                Evergage.util.getValueFromNestedObject(
                  "dataModelFields.field_dmo_industries",
                  pageDetails,
                ) || null,
              Department: () =>
                Evergage.util.getValueFromNestedObject(
                  "dataModelFields.field_departments",
                  pageDetails,
                ) || null,
              JobRole: () =>
                Evergage.util.getValueFromNestedObject(
                  "dataModelFields.taxonomy_vocabulary_23",
                  pageDetails,
                ) || null,
              PageBundle: () => {
                const pageBundle = Evergage.util.getValueFromNestedObject(
                  "entityBundleNice",
                  pageDetails,
                );
                return pageBundle ? [pageBundle] : null;
              },
            },
          },
        },
      },
      {
        name: "blog",
        isMatch: () => {
          if (/\/about\/blog\/\d+\/\d+\/.+/.test(window.location.pathname)) {
            setPageDetailsFromDataLayer();
            return true;
          }
          return false;
        },
        catalog: {
          Blog: {
            _id: () => Evergage.util.getValueFromNestedObject("entityId", pageDetails),
            name: () => Evergage.util.getValueFromNestedObject("entityLabel", pageDetails),
            url: Evergage.resolvers.fromCanonical(),
            imageUrl: Evergage.resolvers.fromMeta("og:image"),
            categories: () => [
              Evergage.util.getValueFromNestedObject("flatTaxonomy.blog_categories", pageDetails),
            ],
          },
        },
        listeners: [
          Evergage.listener("submit", ".premium-access-ajax", () => {
            const eloquaId = findInDataLayer("EloquaGuid");
            if (eloquaId) {
              Evergage.sendEvent({
                action: "Tableau Blog Sign-up",
                user: { attributes: { eloquaId: eloquaId } },
              });
            }
          }),
        ],
        contentZones: [
          /*
                    As in this case below, content zones do not necessarily have to denote content to be replaced, they can be
                    useful for inserting template content before or after the the DOM node with the provided selector.
                    */
          { name: "blog_text_content", selector: ".field--name-field-page-sections" },
        ],
      },
    ],
  };
  Evergage.initSitemap(config);
});
```

## See Also

- [_Salesforce Help_: Identity System Setup for the Web SDK](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity_web_sdk.htm)

<!-- document id=3176a72d0a29d45e06bd75abfac2e93c1f55dbf6399c46d2b69d8ddec1a9fb85 url=/developer/current/en-us/personalization/personalization/guides/web-integration/data-capture-best-practices.md -->

# Best Practices for Data Capture Using Site Mapping

After reviewing all relevant sitemap documentation, move your sitemap from your test dataset to your production environment only after thoroughly testing and validating it. Additionally, the information in this document can prove helpful to reference throughout each phase of implementation. As a final validation for working on a sitemap, we suggest working through the following steps.

The checklists laid out in this document are by no means comprehensive. Instead, they call out common areas where implementors run into trouble while writing sitemap code.

---

## In this article

- [Validate the JavaScript](#validate-the-javascript)
  - [Checklist](#checklist)
- [Use the browser extension to test the sitemap code](#use-the-browser-extension-to-test-the-sitemap-code)
  - [Checklist](#checklist-1)
- [sendEvent function usage](#sendevent-function-usage)
- [Single Page App (SPA) sites](#single-page-app-spa-sites)
- [Timing issues](#timing-issues)
- [Data Capture Sources](#data-capture-sources)
  - [Window Objects](#window-objects)
  - [Meta Tags](#meta-tags)
  - [itemprop](#itemprop)
  - [JSON-LD](#json-ld)
  - [URLs](#urls)
  - [Page Source Code](#page-source-code)
    - [Example](#example)
  - [DisplayUtils](#displayutils)
  - [util.resolveWhenTrue](#utilresolvewhentrue)
  - [Additional Best Practices](#additional-best-practices)

---

## Validate the JavaScript

### Checklist

- Check for common JavaScript errors by reviewing the sitemap code in the sitemap code editor, found in the Personalization Visual Editor. The sitemap code editor helps identify and highlight errors in your code. You can also validate your code by visually spot-checking it for errors.
- Depending on your chosen SDK namespace, use `SalesforceInteractions.cashDom` or `Evergage.cashDom` for each implementation instead of using jQuery or another library that the Personalization platform does not include (such as Knockout). Since the Personalization Beacon includes CashDom (the [`cash`](https://github.com/fabiospampinato/cash#documentation) library), code written using CashDom remains unaffected by updates made to JS libraries found on the client site, thus allowing for greater stability over time.
- Ensure that the sitemap does not manipulate the DOM in any way; that is the function of the Campaigns and Templates system. For more information on using these features on your Web integration, see [About Web Campaigns and Templates](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign.htm) on Salesforce Help.
- When using custom code to supply dates to the backend, ensure the custom code instantiates dates using `new Date(Date.UTC(YYYY, MM, DD))` instead of `new Date(YYYY, MM, DD)`. Using `new Date(YYYY, MM, DD)` can introduce errors due to differences between an end user's timezone and the way dates are stored as UTC.
- Whenever possible, avoid using resolvers in situations where a direct value needs to be ingested since resolvers are designed to return a function. For example, the following examples depict improper use of a resolver.

  ```javascript
var someValue = SalesforceInteractions.resolvers.fromSelector(".someCssSelector");
```

  ```javascript
var someValue = Evergage.resolvers.fromSelector(".someCssSelector");
```

## Use the browser extension to test the sitemap code

- Injecting or forcing the SDK URL to test the sitemap code.
  - [Install the Salesforce Interactions SDK Launcher](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_interactions_sdk_launcher.htm)
  - If you followed the best practices detailed in the [Plan a Web Integration](https://developer.salesforce.com/docs/marketing/personalization/guide/web-integration-planning.md) document, you can validate your sitemap code against an available test dataset.
- After your test dataset runs on the site, click through the mapped pages and check to see that the events are sending as expected.
  - Refer to our documentation on [Event Validation Using Chrome Browser Developer Tools](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-event-validation.md#event-validation-using-chrome-browser-developer-tools).

### Checklist

- No errors in the **Network** tab for each event.
- Mapped attributes are appearing as expected in the events.
- Ensure that the [Sitemap Implementation](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.md) and any [Event API Request](https://developer.salesforce.com/docs/marketing/personalization/event-api/event-options-salesforceinteractions.md) objects in your code are appropriately structured and collect values of the correct type for each option, as described in the documentation for [Attributes](https://developer.salesforce.com/docs/marketing/personalization/data-modeling/attributes.md).
- When collecting `Category` data associated with another item type (`Article`, `Product`, or `Blog`), ensure that the structure and case of category IDs are _exactly_ consistent on all catalog items mapped with categories.
- Carefully validate category ID structures. When mapping the `Category` item type directly, ensure that the value of `id` (or `_id` in the `Evergage` namespace) in the `pageType` is _always_ supplied as a string. Additionally, you can construct a hierarchy of Categories by using `|` separated values to denote each level of the `Category` hierarchy. Ideally, these values are normalized in some way with your sitemap as they are collected. Normalizing these values helps ensure consistency within your catalog. For example, the Personalization platform considers a `Category` with a "Green Hats" ID different from a Category with a "Green hats" ID. In the following example `Category` ID, all the principles and best practices concerning `Category ID` structure have been used: `main-category|sub-cat-1|sub-cat-2`.
- Check whether listeners are binding correctly on each page and are successfully sending events without errors or incorrectly formatted data. For example, if a sitemap has a click listener that listens for a button click to send an `AddToCart` event, ensure that clicking that button sends an `AddToCart` event with all the appropriate `lineItem` data successfully.
- Validate that `onActionEvent` is being used correctly. While it is possible, we strongly discourage the use of event listeners and/or the `sendEvent` function in `onActionEvent`. However, if you do decide that you must use `sendEvent` here, take extra care to make sure that your code includes an exit case. Otherwise, you risk the possibility of triggering an infinite loop. Ensure that `onActionEvent` is not being used to overwrite the contents of the event, instead only to manipulate it and/or append additional data. Additionally, make sure that `onActionEvent` always returns the `ActionEvent`, even if no transformations and/or modifications are made. You can find examples of properly using `onActionEvent` to ingest user attributes in the [Capturing User and Account Attributes](https://developer.salesforce.com/docs/marketing/personalization/guide/capturing-user-account-attributes.md) page.
- Validate that your code is using supported and correctly formatted fields when mapping Page Types. The supported fields are outlined in the [Page Types](https://developer.salesforce.com/docs/marketing/personalization/guide/page-types.md) documentation.
- Ensure that your mapped content zones can serve the customer's use-cases. Refer to the [Content Zones documentation that outlines many commonly mapped content zones to get some ideas.

## sendEvent function usage

Depending on the SDK namespace you use, the following `sendEvent` function is used to send an Event to Personalization. Ensure that events sent using this function strictly follow the structure of the Event API requests, as outlined in the [Event API](https://developer.salesforce.com/docs/marketing/personalization/event-api/event-api.md) documentation.

```javascript
SalesforceInteractions.sendEvent;
```

```javascript
Evergage.sendEvent;
```

**note:** While very similar, the Event API and page types in the sitemap _do_ have different structures.

## Single Page App (SPA) sites

For more information about handling SPA page changes, refer to the [Single Page App (SPA) Handling](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.md#single-page-app-spa-handling) documentation. While using an interval powers the documented example on that page, you can use a different mechanism to monitor the site for page changes at your discretion.

## Timing issues

- Do selectors work in the console or editor, but the sitemap is still unsuccessful in scraping those values when sending the event?

  - The location of the data you are scraping probably does not exist at the time the page matches.
  - Solution:

    - Write a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) for the `isMatch` function that matches the page type, which relies on data not available precisely at page load. The page is matched after the `Promise` resolves, that resolution being delayed until the source of your data exists in the DOM or `window` object.

    **note:** If you do decide to use a Promise, ensure that you include a mechanism that resolves the Promise after a set period, regardless of whether the match condition has been met.

- Does the catalog configuration work in the editor, but the sitemap is still unsuccessful in scraping those values when sending the event?

  - The catalog configuration values are being evaluated when the sitemap is parsed and not when the `pageType` is matched.
  - Solution:

    - Be sure to use custom functions or [`resolvers`](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.md#resolvers) for catalog configuration values. If you do not use functions or resolvers, these fields are evaluated when the browser parses the sitemap object, not when the `pageType` is evaluated.
    - For example:

      ```javascript
      description: () => window.product.description;
      ```

## Data Capture Sources

When deciding on what to capture, first **consider all possible locations where the data is available on the page for that `pageType`**. While testing a new data source, ensure that the method of obtaining the data persists throughout the Page Type and that the data is available when the sitemap executes. For synchronous integrations, this could mean using a `Promise` to resolve the `isMatch` function when data is available or using `Promises` for the catalog ID field until the available data is available to capture.

### Window Objects

Data found within window objects (that is, `window.dataLayer`) tends to be more static and reliable, though be careful about using a third-party vendor. Sites correctly implemented with Shopify, Magento, and Drupal tend to be more reliable than others.

Taken from the [ecommerce example](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps/ecommerce.md), we are able to extract the product details found inside the ecommerce data object in the following examples.

```javascript
const getProductsFromDataLayer = () => {
  if (window.dataLayer) {
    for (let i = 0; i < window.dataLayer.length; i++) {
      if (
        ((window.dataLayer[i].ecommerce && window.dataLayer[i].ecommerce.detail) || {}).products
      ) {
        return window.dataLayer[i].ecommerce.detail.products;
      }
    }
  }
};
```

```javascript
const getProductsFromDataLayer = () => {
  if (window.dataLayer) {
    for (let i = 0; i < window.dataLayer.length; i++) {
      if (
        ((window.dataLayer[i].ecommerce && window.dataLayer[i].ecommerce.detail) || {}).products
      ) {
        return window.dataLayer[i].ecommerce.detail.products;
      }
    }
  }
};
```

You can use the `SalesforceInteractions.resolvers.fromWindow` and `SalesforceInteractions.mcis.getValueFromNestedObject` functions in the `SalesforceInteractions` namespace and `Evergage.resolvers.fromWindow` and `Evergage.util.getValueFromNestedObject` functions in the `Evergage` namespace to return a value from a nested object safely.

For example, when capturing data from `window.dataLayer[0].ecommerce.detail.products`, you could encounter an error if one part of the path is not defined. The `SalesforceInteractions.resolvers.fromWindow` function ( the `Evergage.resolvers.fromWindow` function in the `Evergage` namespace) safely navigates the given path to return a value if it exists or `null` if the nested object, or some object in the path, does not exist.

### Meta Tags

If the data exists within the meta tag and the DOM, meta tag data is a reliable data format. Personalization has a built-in resolver function in the `SalesforceInteractions` and `Evergage` namespaces to retrieve data from meta tags:

```javascript
SalesforceInteractions.resolvers.fromMeta();
```

```javascript
Evergage.resolvers.fromMeta();
```

As an example, say a hypothetical website selling widgets contains the following meta tag for description.

```html
<meta name="description" content="The premier place for all your widget needs." />
```

In a catalog configuration, you can retrieve the description content of that tag with the following code.

```javascript
description: SalesforceInteractions.resolvers.fromMeta("description");
```

```javascript
description: Evergage.resolvers.fromMeta("description");
```

`description` now has the string value: `The premier place for all your widget needs.`

### itemprop

The `itemprop` attribute is used to add properties to an element on the page, describing the content in the element. To learn more about the itemprop attribute, refer to the [itemprop](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemprop) documentation on the [Mozilla Developer Network](https://developer.mozilla.org/en-US/).

Depending on the SDK namespace you're using, Personalization has the following built-in resolver function to retrieve data from elements with a specified `itemprop`. This resolver function returns the content of the first matching element with the given `itemprop`.

```javascript
SalesforceInteractions.resolvers.fromItemProp;
```

```javascript
Evergage.resolvers.fromItemProp;
```

For example, when trying to capture the rating on a product, you could come across a page that contains the following element:

```html
<meta itemprop="ratingValue" content="5" />
```

In a catalog configuration, you can retrieve the rating value of that element with the following code.

```javascript
rating: SalesforceInteractions.resolvers.fromItemProp("ratingValue");
```

```javascript
rating: Evergage.resolvers.fromItemProp("ratingValue");
```

`rating` now has the value `"5"`

### JSON-LD

JSON-LD is a popular way to annotate and describe elements on a page with structured data. Personalization has the following built-in resolver function to parse and retrieve data from a JSON-LD element. This resolver function parses the first JSON-LD script on the page. If given a `path`, it returns the value of the path from the parsed JSON-LD object.

```javascript
SalesforceInteractions.resolvers.fromJsonLd;
```

```javascript
Evergage.resolvers.fromJsonLd;
```

For example, if a site had the following element:

```html
<script type="application/ld+json">
  {
    "@context": "http://schema.org/",
    "@type": "Product",
    "name": "Worlds Greatest Widget",
    "description": "The premier place for all your widget needs.",
    "id": "123",
    "brand": { "@type": "Thing", "name": "Widget" },
    "availability": "http://schema.org/InStock"
  }
</script>
```

In the catalog configuration, you can retrieve the entire object using the preceding resolver function. Alternatively, if you only wanted a single element such as `name`, use the resolver function as shown in the following examples to retrieve the entire object.

```javascript
SalesforceInteractions.resolvers.fromJsonLd("name");
```

```javascript
Evergage.resolvers.fromJsonLd("name");
```

### URLs

A page's URL can contain helpful information that you'd like to capture. For example, you can capture a Product URL directly from the URL the user is visiting using the following resolver function.

```javascript
SalesforceInteractions.resolvers.fromHref;
```

```javascript
Evergage.resolvers.fromHref;
```

Some pages can also contain a canonical link element that is the preferred URL of the page. You can capture canonical URLs using the following resolver function.

```javascript
SalesforceInteractions.resolvers.fromCanonical;
```

```javascript
SalesforceInteractions.resolvers.fromCanonical;
```

### Page Source Code

Sometimes the only source of data is the DOM itself. Personalization has several helper functions that can extract the data you need. The following table lists the helper functions available in the `SalesforceInteractions` and `Evergage` SDK namespaces that you can use to extract text and attributes from elements in the DOM.

| `SalesforceInteractions`                                         | `Evergage`                                         | Description                                 |
| ---------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------- |
| `SalesforceInteractions.resolvers.fromSelector`                  | `Evergage.resolvers.fromSelector`                  | Retrieve data from an element.              |
| `SalesforceInteractions.resolvers.fromSelectorMultiple`          | `Evergage.resolvers.fromSelectorMultiple`          | Retrieve data from multiple elements.       |
| `SalesforceInteractions.resolvers.fromSelectorAttribute`         | `Evergage.resolvers.fromSelectorAttribute`         | Retrieve attributes from an element.        |
| `SalesforceInteractions.resolvers.fromSelectorAttributeMultiple` | `Evergage.resolvers.fromSelectorAttributeMultiple` | Retrieve attributes from multiple elements. |

#### Example

Consider your website's sitemap code has the following element.

```html
<span id="product" data-productId="123">Worlds Greatest Widget</span>
```

In the catalog configuration, you can retrieve the product ID with the following code.

```javascript
id: SalesforceInteractions.resolvers.fromSelectorAttribute("#product", "data-productId");
```

```javascript
_id: Evergage.resolvers.fromSelectorAttribute("#product", "data-productId");
```

You can also retrieve the product's name with the following code.

```javascript
name: SalesforceInteractions.resolvers.fromSelector("#product");
```

```javascript
name: Evergage.resolvers.fromSelector("#product");
```

If you're familiar with [cash](https://kenwheeler.github.io/cash/), you can use `SalesforceInteractions.cashDom` (or `Evergage.cashDom` in the `Evergage` namespace) to retrieve data on the DOM. You can view the list of available utility functions in Evergage.js in the source menu inside the dev tool.

### DisplayUtils

When you do have to use a Promise to wait for data to be available, the [web template display utilities](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/web-campaigns-templates/web-template-display-utilities.md) provide methods that are helpful in waiting for specific elements to be on the page. These methods trigger only when the specified element is loaded on the page.

For example, if you need to wait for the `#productId` element to be on the page in order to capture the ID of a product, you can use `pageElementLoaded` utility as shown in the following examples.

```javascript
id: () => {
  return SalesforceInteractions.DisplayUtil.pageElementLoaded("#productId", "html").then(
    (ele) => {
      return SalesforceInteractions.resolvers.fromSelector("#productId");
    },
  );
};
```

```javascript
_id: () => {
  return Evergage.DisplayUtil.pageElementLoaded("#productId", "html").then((ele) => {
    return Evergage.resolvers.fromSelector("#productId");
  });
};
```

### util.resolveWhenTrue

When you have to wait for data to be available on the page, you can use the following [utility function](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.md#utility-functions) to bind and unbind processes that return a Promise that resolves when the provided function returns a "truthy" value.

```javascript
SalesforceInteractions.util.resolveWhenTrue;
```

```javascript
Evergage.util.resolveWhenTrue;
```

The preceding function also supports a timeout that rejects the Promise if the provided function does not return a "truthy" value within the specified time. For example, if you need to wait for the `window.dataLayer[0].productId` to be available on the page to capture the product ID, you can use the following code.

```javascript
id: () => {
    return SalesforceInteractions.util.resolveWhenTrue.bind(() => {
        let productId = SalesforceInteractions.mcis.getValueFromNestedObject(
            "window.dataLayer[0].productId",
        );
        if (productId) {
            return productId;
        } else {
            return false;
        }
    }, undefined, 1000, 50);
};
```

```javascript
_id: () => {
    return Evergage.util.resolveWhenTrue.bind(() => {
        let productId = Evergage.util.getValueFromNestedObject("window.dataLayer[0].productId");
        if (productId) {
            return productId;
        } else {
            return false;
        }
    }, undefined, 1000, 50);
};
```

### Additional Best Practices

- **Avoid undefined data**
  - If your data field depends on a resolver, include it as a return inside a function to avoid sending undefined data.
- **Practice console logging**
  - Get into a good habit of console logging the data in the sitemap. Just because it was available in Chrome Developer Tools doesn’t guarantee its availability at the precise moment that the Personalization sitemap code is executing. Consider the timing when the data is available.
    - Does it load only after a specific action?
    - Is it only available when the user is logged in?
  - Only use console logging when developing a sitemap. Avoid including these statements in a live sitemap.
- **Test your data source thoroughly**
  - Navigate to the page from a different link
  - Click back and forth on the browser button to ensure the data persists through the change.
  - Some pages can display differently depending on the referring source. This behavior is especially true for single-page applications.
- **Consider backup plans**
  - If the data is available in two separate areas, consider using the second data source as a backup.
  - When creating custom helper functions, always assume the value is not available and null check everything.
- **Ensure clean data capture**
  - Trim and clean the values, especially when it comes to IDs. Errant empty spaces can produce duplicate items in the catalog.
- **Keep your data capture as simple as possible**
  - When using selectors, prefer IDs and unique classes over relative selectors if possible. Long chains of child selectors or selectors using `nth-child` may not always return the same element on pages of the same type.
  - When using selectors on the DOM, reduce the number of selectors to the minimum required to obtain the data.
  - If the selector is too specific, it could capture data incorrectly and differently from the way it does on other Page Types.
- **Double-check data capture from meta tags**
  - Be careful of meta tags; some sites do not always update the meta tags appropriately.

## See Also

- [_Salesforce Help_: Install the Salesforce Interactions SDK Launcher](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_interactions_sdk_launcher.htm)
- [_Salesforce Help_: About Web Campaigns and Templates](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign.htm)
- [_External Link_: Cash Documentation](https://github.com/fabiospampinato/cash#documentation)

<!-- document id=45fcc1309bde00953240c0a1bc8fee479bbba153c412b1a8dbe6afe6c899172b url=/developer/current/en-us/personalization/personalization/guides/custom-interface-template-configuration/properties/boolean.md -->

# Boolean Property

## Simple Checkbox

A basic checkbox input.

```typescript
simpleProperty: boolean = true;
```

![Boolean](https://developer.salesforce.com/media/interface-template-configuration/Boolean.png)

In the preceding example, `true` is the value. `false` or an undefined value is also valid.

<!-- document id=1ccdd838bacd26f501f68e27d8ff3272813e5c08af663a4a5cf8869ade9a1940 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/web-campaigns-templates/campaign-debugger.md -->

# Campaign Debugger

The **Campaign Debugger** tool gives you the details of all Marketing Cloud Personalization activity and data on a page, including:

- Actions
- Campaigns, both enabled and disabled
- Item Data

Before you can enable and use the **Campaign Debugger**, your dataset needs the following:

- Personalization Tools Gear installed
- Beacon Version 16
- Salesforce Interactions SDK Launcher Chrome Extension
- A completed Sitemap

## Usage

To use the **Campaign Debugger**, do the following.

1. Navigate to the page you want to test
2. Click the **Salesforce Interactions SDK Launcher Chrome Extension** icon to open the menu
3. Select **Campaign Debugger**
4. If the Personalization JavaScript beacon is not installed on the page, you must enable **Inject SDK**
   to use the Campaign Debugger.
5. If the Personalization JavaScript beacon is installed, and you would like to test another dataset, you
   should force override the SDK. The URL structure should be:
   `https://ACCOUNT_NAME.evergage.com/beacon/ACCOUNT_NAME/DATASET_NAME/scripts/evergage.js`
6. After enabling the **Campaign Debugger**, refresh the page and click the blue Personalization tab
   on the right side of the page.

The rest of this article details the specific functionalities of the **Campaign Debugger** including:

1. Campaign Debugging - Allows you to test campaigns and experiences
2. Events - Provides details for the current page event
3. Campaign Responses - Details for the campaigns that did return
4. Campaign Explanations - Explanations for the campaigns that did not return

### Campaign Debugging

At the top of the debugger tool you'll see information regarding the account, dataset, beacon version, as well as an
input box and toggle for testing campaigns and experiences. If you're interested in testing a particular campaign, type
a partial campaign name in this box to see it in the dropdown, even if it's disabled. After it is selected,
you're free to begin testing.

#### Campaign & Experience Testing

There are two modes you can test in using the **Campaign Debugger**:

- **Campaign Testing Mode** - Use to simulate unpublished campaign behavior and appearance on your site
- **Experience Testing Mode** - Use to test a specific campaign experience

**Campaign Testing Mode**

If you want to test a campaign to see how would behave on your site for your user account without publishing it:

1. Ensure the **Campaign Debugger** is enabled
2. Select the campaign
3. Enable **Testing Mode** using the toggle switch
4. Click **Apply**
5. You will be redirected to the same page with the query parameter `evergageTestMessages=[CAMPAIGN_ID]` in the URL.
   This will cause the campaign to act like it's published so you can test changes outside of the campaign editor.
   You will see whichever campaign experience your user account would qualify for. This testing mode adheres to all of
   the rules configured for the campaign and experiences. This means that there is a chance your user account is ineligible to see the campaign so you won't see anything displayed on the screen. This does not mean that the campaign
   is not working, since it may be simply that you didn't qualify to see it either due to campaign or experience rules, or
   being added to the campaign or experience control group.

**Experience Testing Mode**

If you want to test a campaign's specific experience:

1. Ensure the **Campaign Debugger** is enabled
2. Select the experience you want to test from the dropdown
3. Enable **Testing Mode** using the toggle switch
4. Click **Apply**
5. This will redirect you to the same page with the query parameter `evergageTestMessages=[EXPERIENCE_ID]` in the URL.
   Experience Testing Mode behavior will be different from **Campaign Testing Mode** behavior because this mode forces your user account to see the specific experience you selected in step 2 even though you may not naturally have qualified to see it. This is because **Experience Testing Mode** ignores any rules at the campaign and experience levels and forces you into the default test group (i.e. you won't see the control). While this mode may not simulate the exact behavior of the published campaign, it will give you the opportunity to preview aesthetic changes outside of the Visual Editor.

**note:** If you don't see the experience with `evergageTestMessages=[EXPERIENCE_ID]` in the URL, there may be some other issue with the campaign. For example, recommendations aren't returning from the server and there's nothing to render. If this happens, the **Campaign Explanations** panel may help elucidate further information. See details below.

### Events

This section shows the raw event JSON going to the Personalization server. This includes details
like:

- User agent
- Content zones included on the page
- userId of the campaign viewer

If there is a mapped item on the page, item data will be shown. This data includes:

- name
- description
- image URL
- a link to the item in the Personalization Catalog.

### Campaign Responses

This section shows a list of campaigns returned from the server for this event. These are campaigns that were returned
as part of the response and (assuming the template client-side code handled the response properly) rendered onto the page.

The details included are:

- Campaign name
- Campaign ID
- Specific Experience ID
- Number of templates rendered
- Whether your user is currently viewing the control or not (Impression Type).

### Campaign Explanations

The last section of the **Campaign Debugger** shows which campaigns did not make it back from the server for this event. This can be due to several common issues, including:

- The campaign is disabled and not being actively tested using the **Campaign Debugger**.
- The server-side template code had an error.
- The Content Zone for the campaign is not on this page.
- The user doesn't meet the rule criteria to see the campaign.
- The items or promotions the campaign intends to return are not be available for this particular configuration.

<!-- document id=bf63d2c6cf6e7173da20415d6596c8526f13ab9d86269aaa2bb4b0ec76ec1f4c url=/developer/current/en-us/personalization/personalization/guides/campaign-development.md -->

# Campaign Development in Marketing Cloud Personalization

After implementing Marketing Cloud Personalization, developers need to shift focus from data ingestion to cross-channel use case execution and enablement. Along with being business user-friendly, Personalization's [Campaign & Templates system](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-development/web-campaigns-templates.md) also empowers developers to determine what data and what level of flexibility a business user has access to.

## Personalization Campaign Types

Personalization campaigns can be broken down into the following four types.

- **Web Campaigns:** To support web campaigns, developers are responsible for integrating Personalization with the client's website (or websites) and developing web templates that business users can leverage to build out campaigns, including A/B/n and rules-based tests.

  **note:** - For information on integrating Personalization with your website, refer to the [Personalization Web Integration documentation](https://developer.salesforce.com/docs/marketing/personalization/guide/web-integration.md).
  - For information on how to leverage campaign templates, refer to the [Web Templates documentation](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-development/web-campaigns-templates.md).

- **Server-Side Campaigns:** Developers can configure templates specifically for server-side campaigns by leveraging a similar approach as web campaigns. A business user can still control test configuration and setup but collaborates more closely with their development team to leverage Personalization's [Event API](https://developer.salesforce.com/docs/marketing/personalization/guide/event-api/event-api.md) correctly for their campaign execution.

  **note:** For information on building a Server-Side Campaign from a template, refer to the [Server-Side Templates documentation](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-development/server-side-campaigns-templates.md)

- **Email Campaigns:** Although email campaigns are developed through the Personalization UI, they require some basic knowledge of HTML. Depending on the business users' capabilities, developers could have limited or no involvement in open-time email campaign development.

  **note:** For information on configuring Open-time Email campaigns, see [Open Time Email Campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_email_campaign.htm) on the Salesforce Help site.

- **Mobile Campaigns:** Personalization can support campaigns for display on mobile devices by using responsive HTML (HTML5) in its standard web templates feature or through integration with native iOS and Android mobile apps.

  **note:** For information on the Personalization Mobile SDK, refer to the [Personalization Mobile Integrations documentation](https://developer.salesforce.com/docs/marketing/personalization/guide/mobile-integration.md).

## See Also

- [_Salesforce Help_: Open Time Email Campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_email_campaign.htm)

<!-- document id=d2a44dc0bc5d33fa5b2f00b63ab4981b12501c7b204a5163349dc6306befdecb url=/developer/current/en-us/personalization/personalization/guides/campaign-development/campaign-template-apis.md -->

# Campaign Template APIs

- [Recommendations](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-template-apis/recommendations.md)
- [Corvus AI](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-template-apis/corvus-ai.md)

<!-- document id=64fcb6e4bd4cb12c63f37952af06ba6aae21de72738ffe926bee37611012f6e1 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/open-time-email-campaigns-templates/capture-email-campaign-url.md -->

# Capture an Open Time Email Campaign URL

Most (if not all) email marketing solutions allow you to embed URLs within content blocks in email templates to either import images and rich media or link to catalog items or item pages. You can use URLs generated by your Marketing Cloud Personalization OTE campaigns to import item images or link to catalog items within your externally managed email campaigns. You can still [create open time email campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_email_campaign_create.htm) using the Personalization UI. However, you do not have to copy over all the generated HTML into your email template. Instead, you can cherry-pick item and item image URLs from your OTE campaign and embed them in your email template.

This article describes how and where to find URLs within a Personalization OTE campaign to copy into your email marketing system. This article assumes that you have created or cloned an OTE campaign, thoroughly tested it, and have the HTML code for the campaign open in front of you. To know more about viewing the HTML for your OTE campaign, see [Capture Open Time Email Campaign URLs](https://help.salesforce.com/s/articleView?id=sf.mc_pers_email_campaign_url.htm).

## Capture URLs from Campaign HTML

The following code sample depicts HTML generated by an example Personalization OTE campaign.

**note:** - In messages that contain more than one content block (such as this sample campaign), the URL for each block differs by one number only.
- The sample code includes the combined code for all the item blocks in the campaign. You can combine all HTML blocks in your campaign by clicking **COMBINE ALL HTML BLOCKS** when viewing the generated HTML in the UI.
- The characters used after `userId` in the sample code are for simulation purposes only. Do not copy these characters into your email marketing solution.

```html
<!-- start Personalization promotion block (Jane Dress Free Shipping Promo) -->
<table
  cellspacing="0"
  cellpadding="0"
  border="0"
  align="center"
  width="100%"
  style="table-layout: fixed;"
>
  <tbody>
    <tr>
      <td width="100%" align="center">
        <div
          class="evergage-block"
          style="max-height: 311px; max-width: 660px; position: relative; overflow: hidden;"
        >
          <a
            href="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE1/1/detail?userId=@@USER_ID@@"
          >
            <img
              src="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE1/1/summary.png?userId=@@USER_ID@@"
              style="max-width: 100%; border: 0;"
              border="0"
              alt="Get free shipping on Jane"
            />
          </a>
        </div>
      </td>
    </tr>
  </tbody>
</table>
<!-- end Personalization promotion block (Jane Dress Free Shipping Promo) -->
<!-- start Personalization Recommendations block (Item Recommendations Row 1) -->
<table
  cellspacing="0"
  cellpadding="0"
  border="0"
  align="center"
  width="100%"
  style="table-layout: fixed;"
>
  <tbody>
    <tr>
      <td width="100%">
        <div
          class="evergage-block"
          style="max-height: 100%; max-width: 100%; position: relative; overflow: hidden; text-align: center;"
        >
          <div class="evergage-recs" style="display: table; width: 100%; max-height: 100%;">
            <span class="evergage-rec" style="display: inline-block;">
              <a
                href="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/1/detail?userId=@@USER_ID@@"
              >
                <img
                  src="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/1/summary.png?userId=@@USER_ID@@"
                  style="max-width: 100%; border: 0;"
                  border="0"
                  alt="Item image"
                />
              </a>
            </span>
            <span class="evergage-rec" style="display: inline-block;">
              <a
                href="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/2/detail?userId=@@USER_ID@@"
              >
                <img
                  src="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/2/summary.png?userId=@@USER_ID@@"
                  style="max-width: 100%; border: 0;"
                  border="0"
                  alt="Item image"
                />
              </a>
            </span>
            <span class="evergage-rec" style="display: inline-block;">
              <a
                href="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/3/detail?userId=@@USER_ID@@"
              >
                <img
                  src="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE2/3/summary.png?userId=@@USER_ID@@"
                  style="max-width: 100%; border: 0;"
                  border="0"
                  alt="Item image"
                />
              </a>
            </span>
          </div>
        </div>
      </td>
    </tr>
  </tbody>
</table>
<!-- end Personalization Recommendations block (Item Recommendations Row 1) -->
<!-- start Personalization Recommendations block (Item Recommendations Row 2) -->
<table
  cellspacing="0"
  cellpadding="0"
  border="0"
  align="center"
  width="100%"
  style="table-layout: fixed;"
>
  <tbody>
    <tr>
      <td width="100%">
        <div
          class="evergage-block"
          style="max-height: 100%; max-width: 100%; position: relative; overflow: hidden; text-align: center;"
        >
          <div class="evergage-recs" style="display: table; width: 100%; max-height: 100%;">
            <span class="evergage-rec" style="display: inline-block;">
              <a
                href="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE3/1/detail?userId=@@USER_ID@@"
              >
                <img
                  src="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE3/1/summary.png?userId=@@USER_ID@@"
                  style="max-width: 100%; border: 0;"
                  border="0"
                  alt=""
                />
              </a>
            </span>
            <span class="evergage-rec" style="display: inline-block;">
              <a
                href="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE3/2/detail?userId=@@USER_ID@@"
              >
                <img
                  src="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE3/2/summary.png?userId=@@USER_ID@@"
                  style="max-width: 100%; border: 0;"
                  border="0"
                  alt=""
                />
              </a>
            </span>
            <span class="evergage-rec" style="display: inline-block;">
              <a
                href="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE3/3/detail?userId=@@USER_ID@@"
              >
                <img
                  src="https://demo.evergage.com/api/dataset/retail/campaign/PTJqe/zIjE3/3/summary.png?userId=@@USER_ID@@"
                  style="max-width: 100%; border: 0;"
                  border="0"
                  alt=""
                />
              </a>
            </span>
          </div>
        </div>
      </td>
    </tr>
  </tbody>
</table>
<!-- end Personalization Recommendations block (Item Recommendations Row 2) -->
```

To copy over URLs from the preceding sample campaign HTML, do the following.

1. Locate the `<a>` and `<img>` tags for each content block in the message.
2. Copy the URL from within each tag and do the following.
   - Replace the number in the middle of the URL with the corresponding item number in the email template. For example, if you've created a 2x2 grid layout to display four items in your OTE campaign, each item and item image URL is allocated a number based on their position in the grid, starting from 1 to 4. If your email template uses different numbering to indicate the location of items within the layout, replace the number in your OTE campaign URL with the corresponding number in your email template.
   - Replace the value after `?userId=` in the URL with the macro or tag your email marketing solution provides for dynamically inserting your recipient's email address.
3. Insert the modified URLs into your email marketing solution wherever necessary.

## Example Campaign URLs

The following are examples of item (`<a>` tag) and item image (`<img>` tag) URLs captured from the preceding sample campaign HTML. `<replaceThis>` in these examples indicates parts of the URL you need to modify before embedding the URL into your email marketing solution.

**`<a>` tag or item URL**

```html
https://demo.evergage.com/api/dataset/retail/campaign/mhegt/jsv81/<replaceThis
  >/detail?userId=<replaceThis></replaceThis
></replaceThis>
```

**`<img>` tag or item image URL**

```html
https://demo.evergage.com/api/dataset/retail/campaign/mhegt/jsv81/<replaceThis
  >/summary.png?userId=<replaceThis></replaceThis
></replaceThis>
```

## See Also

- [_Salesforce Help_: Create an Open Time Email Campaign](https://help.salesforce.com/s/articleView?id=sf.mc_pers_email_campaign_create.htm)
- [_Salesforce Help_: Capture Open Time Email Campaign URLs](https://help.salesforce.com/s/articleView?id=sf.mc_pers_email_campaign_url.htm)

<!-- document id=4c6e09f5c906ce2054e76f195e8b5b852176d2568cd65ad98d2c5ed7515312af url=/developer/current/en-us/personalization/personalization/guides/web-integration/capturing-user-account-attributes.md -->

# Capture User and Account Attributes

The `onActionEvent` method captures user and account attributes to add user data to an event before sending it to Personalization. For more information on the `user` and `account` objects, see the [user object](https://developer.salesforce.com/docs/marketing/personalization/event-api/event-options-salesforceinteractions.md#the-user-object) and the [account object](https://developer.salesforce.com/docs/marketing/personalization/event-api/event-options-salesforceinteractions.md#the-account-object) documentation.

**important:** Account Profiles was retired in August 2024. For more information, see [Personalization Account Profiles Retirement](https://help.salesforce.com/s/articleView?id=001744617&type=1).

## Use onActionEvent in the global Configuration

The following are examples of using the `onActionEvent` method in the `global` configuration.

```javascript
global: {
onActionEvent: (actionEvent) => {
    const email = SalesforceInteractions.cashDom("header.logged-in-user-email").text().trim();
    if (email) {
    actionEvent.user = actionEvent.user || {};
    actionEvent.user.attributes = actionEvent.user.attributes || {};
    actionEvent.user.attributes.emailAddress = email;
    }
    return actionEvent;
};
}
```

```javascript
global: {
onActionEvent: (actionEvent) => {
    const email = Evergage.cashDom("header.logged-in-user-email").text().trim();
    if (email) {
    actionEvent.user = actionEvent.user || {};
    actionEvent.user.attributes = actionEvent.user.attributes || {};
    actionEvent.user.attributes.emailAddress = email;
    }
    return actionEvent;
};
}
```

## Use onActionEvent in the pageTypes Configuration

The following are examples of using the `onActionEvent` method in the `pageTypes` configuration.

```javascript
pageTypes: [
    {
        name: "search",
        isMatch: () => /\/search/.test(window.location.pathname),
        onActionEvent: (actionEvent) => {
            const searchTerm = SalesforceInteractions.cashDom(".content.searchTerm").text().trim();
            if (searchTerm) {
                actionEvent.user = actionEvent.user || {};
                actionEvent.user.attributes = actionEvent.user.attributes || {};
                actionEvent.user.attributes.lastSearchTerm = searchTerm;
            };
            return actionEvent;
        }
    },
],
```

```javascript
pageTypes: [
    {
        name: "search",
        isMatch: () => /\/search/.test(window.location.pathname),
        onActionEvent: (actionEvent) => {
            const searchTerm = Evergage.cashDom(".content.searchTerm").text().trim();
            if (searchTerm) {
                actionEvent.user = actionEvent.user || {};
                actionEvent.user.attributes = actionEvent.user.attributes || {};
                actionEvent.user.attributes.lastSearchTerm = searchTerm;
            };
            return actionEvent;
        }
    },
],
```

## Setting User and Account Attributes Using Event Listeners

In the following code samples, the `onActionEvent` method is used in the `global` configuration. It listens on every page for a form in the footer to be submitted. It then sends an event containing the user's ID and captures the user's email address, which you can then configure for use as an identity. To know more about using captured data as an ID, see the [Event API](https://developer.salesforce.com/docs/marketing/personalization/event-api/event-options-salesforceinteractions.md#the-user-object) documentation.

```javascript
global: {
    listeners: [
        SalesforceInteractions.listener("submit", "form.footer", () => {
            const email = SalesforceInteractions.cashDom("form.footer input.email").val();
            const name = SalesforceInteractions.cashDom("form.footer input.name").val();
            SalesforceInteractions.sendEvent({
                interaction: {
                    name: "Form Submission | Footer",
                },
                user: {
                    identities: {
                        emailAddress: email
                    },
                    attributes: {
                        name: name
                    }
                }
            });
        })
    ]
},
```

```javascript
global: {
    listeners: [
        Evergage.listener("submit", "form.footer", () => {
            const email = Evergage.cashDom("form.footer input.email").val();
            const name = SalesforceInteractions.cashDom("form.footer input.name").val();
            Evergage.sendEvent({
                action: "Form Submission | Footer",
                user: {
                    attributes: {
                        emailAddress: email,
                        name: name
                    }
                }
            });
        })
    ]
},
```

The following examples depict a listener in the `pageTypes` configuration. You can see that the event's structure is the same as the structure of the event sent by the listener in the `global` configuration in the previous namespace-specific examples.

```javascript
pageTypes: [
	{
		name: "preferences",
		isMatch: () => /\/preferences/.test(window.location.pathname),
		interaction: {
			name: "Preferences"
		},
		listeners: [
			SalesforceInteractions.listener("submit", "form.user-prefs", () => {
				const email = SalesforceInteractions.cashDom("form.user-prefs input.email").val();
				const name = SalesforceInteractions.cashDom("form.user-prefs input.name").val();
				SalesforceInteractions.sendEvent({
					interaction: {
						name: "Form Submission | Preferences",
					},
					user: {
						identities: {
							emailAddress: email
						},
						attributes: {
							name: name
						}
					}
				});
			})
		]
	},
],
```

```javascript
pageTypes: [
    {
        name: "preferences",
        isMatch: () => /\/preferences/.test(window.location.pathname),
        listeners: [
            Evergage.listener("submit", "form.user-prefs", () => {
                const email = Evergage.cashDom("form.user-prefs input.email").val();
                const name = SalesforceInteractions.cashDom("form.user-prefs input.name").val();
                Evergage.sendEvent({
                    action: "Form Submission | Preferences",
                    user: {
                        attributes: {
                            emailAddress: email,
                            name: name
                        }
                    }
                });
            })
        ]
    },
],
```

Capturing `account` attributes works the same way as capturing `user` attributes. For the full structure of the `account` object, see the [account object](https://developer.salesforce.com/docs/marketing/personalization/event-api/event-options-salesforceinteractions.md#the-account-object) documentation.

```javascript
global: {
    listeners: [
        SalesforceInteractions.listener("submit", "form.survey", () => {
            const industry = SalesforceInteractions.cashDom("form.survey input.industry").val();
            const employeeSize = SalesforceInteractions.cashDom("form.survey input.employeeSize").val();
            SalesforceInteractions.sendEvent({
                interaction: {
                    name: "Form Submission",
                },
                account: {
                    attributes: {
                        industry: industry,
                        employeeSize: employeeSize
                    }
                }
            });
        })
    ]
},
```

```javascript
global: {
    listeners: [
        Evergage.listener("submit", "form.survey", () => {
            const industry = Evergage.cashDom("form.survey input.industry").val();
            const employeeSize = Evergage.cashDom("form.survey input.employeeSize").val();
            Evergage.sendEvent({
                action: "Form Submission",
                account: {
                    attributes: {
                        industry: industry,
                        employeeSize: employeeSize
                    }
                }
            });
        })
    ]
},
```

## See Also

- _Salesforce Help_: [Create a User Profile Object](https://help.salesforce.com/s/articleView?id=sf.mc_pers_user_profile_object_create.htm)

<!-- document id=b5ab064b1fd3c38f3aec36bf8a8f7c1751d41e75c4a5147fe43bec93b76b2ceb url=/developer/current/en-us/personalization/personalization/guides/data-modeling/catalog.md -->

# Catalog

The Marketing Cloud Personalization platform can model key business objects as objects within a shadow catalog. This configuration happens within the Personalization [catalog setup](https://help.salesforce.com/s/articleView?id=sf.mc_pers_catalog_profile.htm) screens.

## Catalog Objects

Catalog objects, such as products or articles, represent key business objects with which a user can interact. You can configure these objects with a name, labels, [custom attributes](https://developer.salesforce.com/docs/marketing/personalization/guide/attributes.md), and related catalog objects. User behavior is tracked against objects as well as against their related catalog objects.

## Attributes

Catalog objects and object types can also have attributes that you can customize based on business requirements. You can configure custom attributes for objects in addition to objects that are already available to reflect supplementary information about the object such as price, date added, or image alternate text for products or author, subject, or keyword for blogs and articles.

A catalog object's attributes must satisfy the following conditions to be promoted and appear in Personalization Recommendations:

- The value of the `archived` attribute must be `false`.
- The value of the `promotionState` attribute must not be `Excluded`.
- The `expiration` date (if any) must not be before the current date.
- The `published` date (if any) must not be after the current date.

In addition to satisfying the conditions listed above, all catalog objects must have values for their `name` and `url` attributes. Additionally, objects of the type `Product` must also have a `price` greater than zero, an `inventoryCount` greater than zero, and a value for their `imageUrl` attribute.

**important:** The `publishedDate` attribute must be exclusively used for articles and blogs. For other use cases, create a new custom attribute.

## Catalog and Profile Objects

Personalization uses Catalog and Profile Objects as foundational components to establish a thorough understanding of a customer's business context and a user's relations to that business context. Catalog Objects help build out an understanding of a customer's business. Additionally, catalog objects can be assigned to other catalog objects as related catalog objects to further describe those objects or define relationships between catalog objects. Examples of catalog object types include products, articles, blogs, promotions/offers, brands, styles, categories, and so on.

Profile Objects improve data dimensionality by allowing you to configure and manage customizable objects on a profile in addition to the [profile attributes](https://help.salesforce.com/s/articleView?id=sf.mc_pers_account_profile_attributes_create.htm) already available. You can set up profile objects the same way you configure catalog objects. You can also assign related catalog objects to profile objects. Data stored within a profile object is accessible via a set of out-of-the-box rules, allowing you to leverage this data for insights and cross-channel experience activation. Real-world examples of Profile Object types include Product Registrations, Vehicle Lease, Home Mortgage, Service Cases, and so on.

## Interactions

Interactions model a user's interaction with an object. Examples include:

- View
- Add to Cart
- Purchase

## See Also

- [_Salesforce Help_: Catalogs and Profiles](https://help.salesforce.com/s/articleView?id=sf.mc_pers_catalog_profile.htm)
- [_Salesforce Help_: Create an Account Profile Attribute](https://help.salesforce.com/s/articleView?language=en_US&id=sf.mc_pers_account_profile_attributes_create.htm)

<!-- document id=f22f094fd6077ffa7a7a7ee6c1db3a3f14da6243b47719375b781deab8144936 url=/developer/current/en-us/personalization/personalization/guides/custom-interface-template-configuration/properties/color.md -->

# Color Property

## Color Picker

A basic color picker input.

```typescript
colorProperty: Color;
```

![Color Picker](https://developer.salesforce.com/media/interface-template-configuration/Color.png)

The value returned from the selection contains both the hex value and the RGB value.

The object structure is as follows:

```typescript
{
  hex: string;
  a: number;
  b: number;
  g: number;
  r: number;
}
```

<!-- document id=939cd093cc655d5b9b416d4d12162bfde1a7a9bbc1debbbc8d33c57486449ce8 url=/developer/current/en-us/personalization/personalization/guides/web-integration/comparison-shopping.md -->

# Comparison Shopping

Comparison Shopping is a specific type of action that occurs whenever a visitor copies a product name onto their clipboard and then leaves the page. By tracking this action, you can identify visitors who look up a product's price on your website and then compares it with prices of the same or similar products across other websites and online suppliers. While there are a number of ways to implement tracking for comparison shopping behavior for business users of Marketing Cloud Personalization, we highly recommend doing so in the Sitemap for a Personalization dataset.

After it is implemented, business users can then track comparison shopping actions either for segmentation or to render campaigns triggered by comparison shopping actions (as long as those actions contain the necessary content zone used by the Template in that Campaign).

**note:** To know more about the business uses of Comparison Shopping, see [Comparison Shopping](https://help.salesforce.com/s/articleView?id=mc_pers_web_campaign_comparison_shopping) on Salesforce Help.

This article explains how you can implement the tracking of Comparison Shopping actions in a Personalization Sitemap.

## Prerequisites

Before implementing Comparison Shopping tracking using the following example as reference, ensure that your Personalization Sitemap is functional and has at least one working `pageType`.

For more information, refer to the [Personalization Web Integration](https://developer.salesforce.com/docs/marketing/personalization/web-integration.md) documentation.

### Comparison Shopping as a Listener

Although there are other ways to set up a Comparison Shopping action, we advise using a [Listener](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemapping-getting-started.md#listeners). The following are namespace-specific examples of setting up a listener that targets the element containing the product name.

```javascript
// definition of SalesforceInteractions.ComparisonShopping
SalesforceInteractions.ComparisonShopping = (() => {
  let productNameCopied = false;

  const bindComparisonShoppingCopy = (event) => {
    SalesforceInteractions.cashDom(event.currentTarget).on("copy.evgComparisonShopping", () => {
      try {
        productNameCopied = true;
      } catch (e) {
        SalesforceInteractions.sendException(e, "bindComparisonShopping: copy event");
      }
    });
  };

  const bindComparisonShoppingBlur = () => {
    try {
      SalesforceInteractions.cashDom(window).on("blur.evgComparisonShopping", () => {
        if (productNameCopied) {
          SalesforceInteractions.sendEvent({
            interaction: {
              name: "Comparison Shopping",
            },
            source: {
              contentZones:
                SalesforceInteractions.mcis.getSitemapResult().currentPage.source.contentZones,
            },
          });
          productNameCopied = false;
        }
      });
    } catch (e) {
      SalesforceInteractions.sendException(e, "handleComparisonShopping");
    }
  };

  return {
    handleComparisonShopping: (event) => {
      SalesforceInteractions.cashDom(window).off(".evgComparisonShopping");
      bindComparisonShoppingCopy(event);
      bindComparisonShoppingBlur();
    },
  };
})();

SalesforceInteractions.init().then(() => {
  // sitemap
  const config = {
    pageTypes: [
      {
        // ...
        listeners: [
          SalesforceInteractions.listener(
            "mouseup.initComparisonShopping touchend.initComparisonShopping",
            ".pdp-primary-info .product-name",
            SalesforceInteractions.ComparisonShopping.handleComparisonShopping,
          ),
        ],
      },
    ],
  };

  // ...
});
```

```javascript
// definition of Evergage.ComparisonShopping
Evergage.ComparisonShopping = (() => {
  let productNameCopied = false;

  const bindComparisonShoppingCopy = (event) => {
    Evergage.cashDom(event.currentTarget).on("copy.evgComparisonShopping", () => {
      try {
        productNameCopied = true;
      } catch (e) {
        Evergage.sendException(e, "bindComparisonShopping: copy event");
      }
    });
  };

  const bindComparisonShoppingBlur = () => {
    try {
      Evergage.cashDom(window).on("blur.evgComparisonShopping", () => {
        if (productNameCopied) {
          Evergage.sendEvent({
            action: "Comparison Shopping",
            source: {
              contentZones: Evergage.getCurrentPage().source.contentZones,
            },
          });
          productNameCopied = false;
        }
      });
    } catch (e) {
      Evergage.sendException(e, "handleComparisonShopping");
    }
  };

  return {
    handleComparisonShopping: (event) => {
      Evergage.cashDom(window).off(".evgComparisonShopping");
      bindComparisonShoppingCopy(event);
      bindComparisonShoppingBlur();
    },
  };
})();

Evergage.init().then(() => {
  // sitemap
  const config = {
    pageTypes: [
      {
        // ...
        listeners: [
          Evergage.listener(
            "mouseup.initComparisonShopping touchend.initComparisonShopping",
            ".pdp-primary-info .product-name",
            Evergage.ComparisonShopping.handleComparisonShopping,
          ),
        ],
      },
    ],
  };

  // ...
});
```

**important:** When leveraging a comparison shopping action to trigger a Campaign, the event must include the content zone used by the Template in that Campaign for it to be included in the response from the `sendEvent` call. Otherwise, events that do not include the content zones targeted by the Campaign do not trigger it.

## See Also

- [_Salesforce Help_: Comparison Shopping Web Campaigns](https://help.salesforce.com/s/articleView?id=mc_pers_web_campaign_comparison_shopping)

<!-- document id=6240aa4517188e6c17f1a87892c499518ae28d505a2b38bc22f38435b6598658 url=/developer/current/en-us/personalization/personalization/guides/custom-interface-template-configuration/properties/complex-object.md -->

# Complex Object

## Complex Types

Configurations can be more complicated groups of fields represented by another TypeScript class. Those classes can have multiple properties and use all the same features of the properties in the parent configuration class.

```typescript
export class ComplexType {
  firstProperty: string;
  secondProperty: number;
}

export class SimpleTemplate implements CampaignTemplateComponent {
  myProperty: ComplexType;
}
```

![Complex](https://developer.salesforce.com/media/interface-template-configuration/Complex.png)

Complex types defined within gears can be used by Templates.

## See Also

- [Select Property](https://developer.salesforce.com/docs/marketing/personalization/guide/select.md)
- [Arrays](https://developer.salesforce.com/docs/marketing/personalization/arrays.md)

<!-- document id=fdbcb2905a9c1dae7d047e04754d771ba2a75b1ed95ee396d91b2853e340fad4 url=/developer/current/en-us/personalization/personalization/guides/web-integration/content-security-policies-javascript-beacon-directives.md -->

# Content Security Policies and Personalization JavaScript Beacon Directives

The Personalization JavaScript beacon currently uses the [`unsafe-eval`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#unsafe_keyword_values) directive, which allows the use of dynamic code evaluation functions such as `eval()`. As part of our ongoing efforts to enhance security standards, we're working on removing the dependency on `unsafe-eval` in the JavaScript beacon.

In the meantime, if your organization's security scanner flags the presence of the `unsafe-eval` directive in the JavaScript beacon, include the [`unsafe-inline`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#unsafe_keyword_values) directive in your [Content Security Policy](https://developer.salesforce.com/docs/marketing/personalization/guide/managing-cors-with-sdk-launcher.md##content-security-policy) as a workaround.

Add the [`unsafe-inline`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#unsafe_keyword_values) directive to your Content Security Policy, especially if:

- your site has a pre-existing Content Security Policy
- you're using web templates and have the Handlebars Gear enabled
- you haven't already included the `unsafe-inline` directive in your Content Security Policy.

**note:** - If you're already using `unsafe-eval` elsewhere, you don't have to immediately stop using it. However, you must include the `unsafe-inline` directive in your Content Security Policy. If your Content Security Policy does not currently have `unsafe-eval` but includes `unsafe-inline`, you should not encounter any issues.
- The changes we're making to the JavaScript beacon are designed with backward compatibility in mind. This approach ensures that you have ample time for conducting security reviews and obtaining necessary approvals before making adjustments to your Content Security Policy.

## See Also

- _Salesforce Developers_: [Managing CORS with the Salesforce Interactions SDK Launcher](https://developer.salesforce.com/docs/marketing/personalization/guide/managing-cors-with-sdk-launcher.md)
- _Salesforce Developers_: [Web Template Handlebars](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/templates/web-template-handlebars.md)
- _External Link_: [MDN Web Docs: `Content-Security-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)

<!-- document id=69a8d5c5c3ddf316e1c4b87a5a1345340b8254d3d6c6d6395e00df0656a6865b url=/developer/current/en-us/personalization/personalization/guides/web-integration/content-zones.md -->

# Content Zones

Content zones are areas throughout a website that you can define to render Personalization campaigns. The web and server-side campaign templates that you create using the Personalization UI reference these content zones within campaigns. You can define content zones globally in the `globalConfig` or for a specific page type in the `pageType` configuration.

## Content Zone Fields

This table summarizes the fields that a content zones accepts.

| Field Name | Expected Value Type | Required | Description                                                                              |
| ---------- | ------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `name`     | String              | **Yes**  | The name of the content zones. Example: `global_popup`, `product_detail_recommendations` |
| `selector` | String              | No       | The CSS selector for the content zones target.                                           |

**note:** All content zones require a `name`, while `selector` is optional. You can still use a content zone without a selector in templates that target the glass pane, such as a popup.

## Common Content Zones

Depending on the type of website, we recommend defining certain Content Zones over others to use specific global templates.

This table outlines content zones that help you use specific global templates without additional content zone configuration if mapped via the sitemap.

| Content Zone                    | Global Template                                                             | Description                                                     |
| ------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `home_hero`                     | Banner with Call-to-Action                                                  | Content zone for a hero banner on the home page                 |
| `home_recs`                     | Einstein Content Recommendations                                            | Content zone for recommendations on home page                   |
| `product_detail_recs_row_1`     | Einstein Product Recommendations                                            | Content zone for recommendations on a `product_detail` page     |
| `product_detail_recs_row_2`     | Einstein Product Recommendations                                            | Content zone for recommendations on a `product_detail` page     |
| `category_recs`                 | Einstein Product Recommendations                                            | Content zone for recommendations on a category page             |
| `cart_recs_row_1`               | Einstein Product Recommendations                                            | Content zone for recommendations on the cart page               |
| `cart_recs_row_2`               | Einstein Product Recommendations                                            | Content zone for recommendations on the cart page               |
| `search_recs`                   | Einstein Content Recommendations, Einstein Product Recommendations          | Content zone for recommendations on the search page             |
| `order_confirmation_recs_row_1` | Einstein Product Recommendations                                            | Content zone for recommendations on the order confirmation page |
| `order_confirmation_recs_row_2` | Einstein Product Recommendations                                            | Content zone for recommendations on the order confirmation page |
| `error_page_recs`               | Einstein Product Recommendations                                            | Content zone for recommendations on an error page               |
| `add_to_cart_modal_recs`        | Einstein Product Recommendations                                            | Content zone for recommendations on an Add to Cart Modal        |
| `global_popup`                  | Exit Intent Popup with Email Capture, Exit Intent Popup                     | Content zone for a global popup                                 |
| `global_infobar_top_of_page`    | Infobar With Call-To-Action, Infobar With User Attribute and Call-To-Action | Content zone for an info bar at the beginning of the page       |
| `global_infobar_bottom_of_page` | Infobar With Call-To-Action, Infobar With User Attribute and Call-To-Action | Content zone for an info bar at the end of the page             |
| `global_slide_in`               | Slide-In with Call-To-Action                                                | Content zone for slide-in messages with call-to-action          |

## See Also

For code samples and example content zone implementations, see:

- [Get Started with Site Mapping](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemapping-getting-started.md)
- [Server-Side Campaigns and Content Zones](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/server-side-campaigns-templates/server-side-campaigns-content-zones.md)
- [Modify Global Templates](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/templates/modifying-global-templates.md)
- [Example Sitemaps](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps.md)

<!-- document id=c646f783927fe9bad6b51361bfb8a0ac841cc137d2561ac49bbd166384a41302 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/campaign-template-apis/corvus-ai.md -->

# Corvus AI

The Corvus AI is a service responsible for training the Contextual Bandit leveraged in Einstein Decisions. That service is made available through the Corvus gear, which allows the fetching of Contextual Bandit arms from within the context of a campaign template.

## Usage

Import `ContextualBanditConfig` into any template and define a configuration, declaring the content zone, maximum number of promotions returned (up to 12), and explicit fallback promotions to use. Optionally, include a filter on which promotions are eligible for the bandit.

Import the `decide` function to be used to request contextual bandit promotions from within the template's `run` method in the server-side TypeScript. The `decide` function adheres to the following type signature.

```typescript
decide(campaignComponentContext, contextualBanditConfig, promotionFilter) => Promotion[]
```

## Example Template

The following is an example template that leverages `ContextualBanditConfig`.

```typescript
import { ContextualBanditConfig, decide } from "corvus";

export class CorvusTemplate implements CampaignTemplateComponent {
  run(context: CampaignComponentContext) {
    const banditConfig: ContextualBanditConfig = {
      contentZone: context.contentZone,
      maxResults: 3,
      fallbackArms: ["arm01"],
    } as ContextualBanditConfig;

    const geoPoint: GeographicPoint = {
      latitude: context.user.location.geographicPoint.latitude,
      longitude: context.user.location.geographicPoint.longitude,
    } as GeographicPoint;
    const geoFence: GeoFence = { radius: 1000, point: geoPoint } as GeoFence;
    const promotionFilter: PromotionFilter = context.services.promotionCatalog
      .promotionFilter(banditConfig.contentZone)
      .withGeoFence(geoFence) as PromotionFilter;
    return {
      promotions: decide(context, banditConfig, promotionFilter),
    };
  }
}
```

## Click Tracking

To properly train the contextual bandit, it is essential to ensure click log generation. The Einstein Decisions global web template automatically tracks click logs and view logs in web campaigns. However, only view logs are tracked automatically in server-side Einstein Decisions campaigns, while clicks require manual tracking.

For instructions on ensuring clicks are correctly tracked, refer to the [Einstein Decisions - Server-Side Template](https://developer.salesforce.com/docs/marketing/personalization/server-side-campaigns-templates/einstein-decisions-server-side-template.md#tracking-click-logs) documentation.

<!-- document id=faa8d415b283c7638989d1259033a4c2dfb16b4275470cacdadff718a471701b url=/developer/current/en-us/personalization/personalization/guides/web-integration/custom-events.md -->

# Custom Events

The Salesforce Interactions SDK and the Personalization module feature several built-in [CustomEvents](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) that you can use to bind listeners specific to the Web SDK. You can find the data passed by these CustomEvents in the `detail` property of the event object passed to a listener's callback function.

## List of Custom Events

The Salesforce Interactions SDK and Personalization module provide the following built-in custom CustomEvents in each of the namespaces.

```javascript
SalesforceInteractions.mcis.CustomEvents = {
  OnEventResponse: "mcis:onEventResponse",
  OnBeforeEventSend: "mcis:onBeforeEventSend",
  OnStatSend: "mcis:onStatSend",
  OnTemplateDisplayEnd: "mcis:onTemplateDisplayEnd",
  OnInit: "mcis:onInit",
};

SalesforceInteractions.CustomEvents = {
  OnBeforeEventSend: "interactions:onBeforeEventSend",
  OnClearPersistedIdentities: "interactions:onClearPersistedIdentities",
  OnConsentRevoke: "interactions:onConsentRevoke",
  OnException: "interactions:onException",
  OnInit: "interactions:onInit",
  OnInitSitemap: "interactions:onInitSitemap",
  OnPageMatchStatusUpdated: "interactions:onPageMatchStatusUpdated",
  OnResetAnonymousId: "interactions:onResetAnonymousId",
  OnSetAnonymousId: "interactions:onSetAnonymousId",
  OnShutDown: "interactions:onShutDown",
  OnClearCookie: "interactions:onClearCookie",
};
```

```javascript
Evergage.CustomEvents = {
  OnEventResponse: "evergage:onEventResponse",
  OnEventSend: "evergage:onEventSend",
  OnStatSend: "evergage:onStatSend",
  OnException: "evergage:onException",
  OnTemplateDisplayEnd: "evergage:onTemplateDisplayEnd",
  OnPageMatchStatusUpdated: "evergage:onPageMatchStatusUpdated",
  OnInit: "evergage:onInit",
  OnInitSitemap: "evergage:onInitSitemap",
  OnShutDown: "evergage:onShutDown",
  OnConsentRevoke: "evergage:OnConsentRevoke",
};
```

## Example Usage

The following code sample depicts how you can use an `mcis:onStatSend` or `evergage:onStatSend` CustomEvent to dispatch a CustomEvent whenever a campaign stat is logged and sent via `Evergage.sendStat`.

```javascript
document.addEventListener(SalesforceInteractions.mcis.CustomEvents.OnStatSend, (domEvent) => {
  console.log(domEvent.detail.campaignStat.stat); // will log "Impression" after the `sendStat` call below
});

const stat = {
  experienceId: "test",
  control: false,
  stat: "Impression",
};

SalesforceInteractions.mcis.sendStat({ campaignStats: [stat] });
```

```javascript
document.addEventListener(Evergage.CustomEvents.OnStatSend, (domEvent) => {
  console.log(domEvent.detail.campaignStat.stat); // will log "Impression" after the `sendStat` call below
});

const stat = {
  experienceId: "test",
  control: false,
  stat: "Impression",
};

Evergage.sendStat({ campaignStats: [stat] });
```

---

## Specifications

### OnEventResponse

The `mcis:onEventResponse` or `evergage:onEventResponse` CustomEvent is dispatched whenever an [Event API](https://developer.salesforce.com/docs/marketing/personalization/event-api/event-api.md) request returns a response. This CustomEvent contains the `actionEvent` payload sent to the Event API and any returned campaign data, such as the names and IDs of campaigns and experiences.

The `OnEventResponse` CustomEvent contains the following `detail`.

```typescript
detail: {
    response: ActionEventResponse,
    actionEvent: ActionEvent | undefined
}
```

#### ActionEventResponse

The `ActionEventResponse` object has the following structure.

```typescript
{
  campaignResponses: CampaignResponse[],
  compiledCampaignTemplates: any,
  errorCode: number
}
```

#### ActionEvent

The `ActionEvent` object has the following structure.

```typescript
{
  action?: string;
  itemAction?: ItemAction;
  interaction?: Interaction;
  user: UserPayload;
  debug?: DebugPayload;
  account?: AccountPayload;
  consents?: Consent[];
  flags?: FlagsPayload;
  source?: SourcePayload;
  catalog?: CatalogPayload;
  order?: OrderPayload;
  cart?: CartPayload;
  performance?: PerformancePayload;
  explain?: boolean;
  pageView?: boolean;
  time?: number;
}
```

---

### OnEventSend

The `mcis:onBeforeEventSend` or `evergage:onEventSend` CustomEvent is dispatched before an event is sent to Personalization. This CustomEvent has the following structure and contains the `actionEvent` payload to be processed in the event pipeline. Both CustomEvents can be canceled to prevent the event from being sent to Personalization.

```typescript
detail: {
  actionEvent: ActionEvent;
}
```

#### ActionEvent

The `ActionEvent` object has the following structure.

```typescript
{
  action?: string;
  itemAction?: ItemAction;
  interaction?: Interaction;
  user: UserPayload;
  debug?: DebugPayload;
  account?: AccountPayload;
  consents?: Consent[];
  flags?: FlagsPayload;
  source?: SourcePayload;
  catalog?: CatalogPayload;
  order?: OrderPayload;
  cart?: CartPayload;
  performance?: PerformancePayload;
  explain?: boolean;
  pageView?: boolean;
  time?: number;
}
```

The following code example depicts canceling the `OnEventSend` CustomEvent to prevent the event from being sent to Personalization.

```javascript
document.addEventListener(SalesforceInteractions.CustomEvents.mcis.OnBeforeEventSend, (event) => {
  event.preventDefault();
});
```

```javascript
document.addEventListener(Evergage.CustomEvents.OnEventSend, (event) => {
  event.preventDefault();
});
```

---

### OnException

The `interactions:onException` or `evergage:onException` CustomEvent is dispatched when an operation fails and contains information about the error and its context. You can use the `OnException` CustomEvent for debugging and logging runtime errors.

The `OnException` CustomEvent contains the following `detail`.

```typescript
detail: {
    error: Error,
    context: string
}
```

#### Error

The `Error` object has the following structure.

```typescript
{
  stack?: string;
}
```

---

### OnInit

The `mcis:onInit` or `evergage:onInit` CustomEvent is dispatched when the Personalization module of the Salesforce Interactions SDK is initialized. You can use the `OnInit` CustomEvent for debugging [single-page applications (SPA)](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.md#single-page-app-handling) where the beacon and the sitemap usually have to reinitialize without a page load event.

The `OnInit` CustomEvent contains the following `detail`.

```typescript
detail: {
    beaconConfig?: Partial<BeaconConfig>
}
```

**note:** The `BeaconConfig` object contains internal configuration in order for the Web SDK to run properly. Do not reference these fields as they are subject to change.

---

### OnShutDown

The `interactions:onShutDown` or `evergage:onShutDown` CustomEvent is dispatched whenever the Salesforce Interactions Web SDK is shut down and contains the shutdown message with the following `detail`.

```typescript
detail: {
  message: string;
}
```

---

### OnInitSitemap

The `interactions:onInitSitemap` or `evergage:onInitSitemap` CustomEvent is dispatched whenever a sitemap is initialized via the `SalesforceInteractions.initSitemap` or `Evergage.initSitemap` function and contains the following `detail`.

```typescript
detail: {
  sitemapConfig: SiteMapConfig;
}
```

#### SiteMapConfig

The `SiteMapConfig` object has the following structure.

```typescript
{
  currentKey?: string,
  global: GlobalConfig,
  pageTypeDefault?: DefaultPageConfig
  pageTypes: pageTypeConfig[],
  settings?: object
}
```

---

### OnPageMatchStatusUpdated

The `interactions:onPageMatchStatusUpdated` or `evergage:onPageMatchStatusUpdated` CustomEvent is dispatched whenever the match status of a sitemap's page type is updated. The `matchStatus` array accumulates every time an `OnPageMatchStatusUpdated` CustomEvent is dispatched, in the order the match statuses are updated. If the status is `running`, the `PageMatchStatus` includes the start time. Conversely, if the status is `selected`, `rejected`, or `matched`, the `PageMatchStatus` includes the end time. The `selected` page type is the first page type to be matched. The sitemap does not evaluate other `matched` page types.

The `OnPageMatchStatusUpdated` CustomEvent contains the following `detail`.

```typescript
detail: {
    matchStatus: PageMatchStatus[]
}
```

#### PageMatchStatus

The `PageMatchStatus` object has the following structure.

```typescript
{
  pageName: string;
  status: MatchStatus;
  startTime?: number;
  endTime?: number;
  _reject?: any;
}
```

---

### OnStatSend

The `mcis:onStatSend` or `evergage:onStatSend` CustomEvent is dispatched when a stat is tracked and can be used to [send Personalization campaign stats to third-party tracking tools](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/templates/campaign-stats-tracking.md#sending-campaign-stats-to-third-parties), such as Google Analytics and Adobe Analytics.

**note:** The `OnStatSend` CustomEvent is dispatched with or without the Campaign Stats Gear. For more information on sending campaign stats with or without the Campaign Stats Gear, refer to the [Campaign Stats Tracking](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/templates/campaign-stats-tracking.md) documentation.

The `OnStatSend` CustomEvent contains the following `detail`.

```typescript
detail: {
    campaignStat: CampaignStat,
    campaignResponse: CampaignResponse
}
```

#### CampaignStat

The `CampaignStat` object has the following structure.

```typescript
{
  experienceId: string;
  stat: 'Send' | 'Impression' | 'Click' | 'Dismissal';
  control: boolean;
  catalog?: { [itemTypeKey: string]: string[] };
}
```

#### CampaignResponse

The `CampaignResponse` object has the following structure.

```typescript
{
  campaignId: string;
  campaignJavascriptContent: string;
  campaignName: string;
  campaignType: string;
  experienceId: string;
  experienceName: string;
  experienceSourceCode: string;
  payload: object
  state: string;
  templateNames: string[];
  type: string;
  userGroup: string;
}
```

---

### OnTemplateDisplayEnd

When enabled, the Handlebars Gear dispatches the `mcis:onTemplateDisplayEnd` or `evergage:onTemplateDisplayEnd` CustomEvent on rendering templates. The Campaign Stats Gear listens for this CustomEvent to track campaign stats. Server-side campaigns require the `OnTemplateDisplayEnd` CustomEvent to be manually dispatched. For instructions on how to dispatch an `OnTemplateDisplayEnd` CustomEvent manually without the Handlebars Gear, refer to the [Web Campaign Stats](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/templates/campaign-stats-tracking.md#use-without-handlebars-and-client-side-code) documentation.

The `OnTemplateDisplayEnd` CustomEvent contains the following `detail`.

```typescript
detail: {
  payload: any;
}
```

---

### OnConsentRevoke

The `interactions:onConsentRevoke` or `evergage:onConsentRevoke` CustomEvent is dispatched when a Consents status is changed from `Opt In` to `Opt Out`. This CustomEvent contains information about the Consent that was revoked with the following detail.

```typescript
detail: {
    consent: Consent,
    lastUpdateTime: number,
    lastSentTime?: number
}
```

#### Consent

The `Consent` object included in the `OnConsentRevoke` CustomEvent detail is the consent that was updated and has the following structure.

```typescript
{
  purpose: string,
  provider: string,
  status: "Opt Out"
}
```

---

## SalesforceInteractions CustomEvents

The following CustomEvents are only dispatched on the `SalesforceInteractions` namespace.

### OnBeforeEventSend

The `interactions:onBeforeEventSend` CustomEvent is dispatched by the Salesforce Interactions Web SDK before an event is sent to any modules. This CustomEvent contains the event from the Salesforce Interactions Web SDK and the following detail.

```typescript
{
  actionEvent: ActionEvent<Interaction>;
}
```

#### ActionEvent<Interaction>

The `ActionEvent<Interaction>` object has the following structure.

```typescript
{
  interaction: Interaction;
  user?: User;
  account?: Account;
  source?: Source;
  consents?: Consent[];
  explain?: boolean;
  pageView?: boolean;
  time?: number;
  performance?: PerformanceMetrics;
}
```

### OnSetAnonymousId

The `interactions:onSetAnonymousId` CustomEvent is dispatched when an anonymousId is set and contains the following detail.

```typescript
{
  newAnonymousId: string;
}
```

---

### OnResetAnonymousId

The `interactions:onResetAnonymousId` CustomEvent is dispatched when the anonymousId is reset through a call to `SalesforceInteractions.resetAnonymousId`.

---

### OnClearCookie

The `interactions:onClearCookie` CustomEvent is not dispatched by the Salesforce Interactions Web SDK but can be manually dispatched to clear any cookies set by the Web SDK. This CustomEvent can be used to instruct the Salesforce Interactions Web SDK to remove any cookies it has set. The `interactions:onClearCookie` CustomEvent optionally allows for the following detail where `domain` is the `cookieDomain` used for setting cookies in the Web SDK.

```typescript
{
  options: {
    domain: string;
  }
}
```

The following code sample depicts dispatching this CustomEvent with a specified domain.

```javascript
document.dispatchEvent(new CustomEvent(SalesforceInteractions.CustomEvents.OnClearCookie), {
  detail: {
    options: {
      domain: domain,
    },
  },
});
```

## See Also

- [_External Link_: CustomEvent Documentation](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent)

<!-- document id=041d44048ba62e01c9735b23a5f0eaa453a24df0c05c38dd72263189d471f54e url=/developer/current/en-us/personalization/personalization/guides/custom-interface-template-configuration.md -->

# Custom Interface and Template Configuration

The Gears configuration system enables the development of custom interface configurations to users of the Marketing Cloud Personalization UI. With this system, a Gear developer can tailor the setup interface for business requirements. These custom interface configurations can be used in the development of Personalization Campaign Templates as well as configuration screens within the Gears system.

## Configurable types

The following Gear types support configuration:

- GearLifecycle
- SegmentExporter
- UserSegmentRule
- AccountSegmentRule
- ContextualRule
- CampaignTemplate

The specification of configuration inputs is done by adding properties to the configurable component. Configuration types can also be shared with CampaignTemplate gears so that templates can use the configuration objects from gears providing campaign services. For example, the `RecommendationConfiguration` class provides the user interface for users to configure the use of calls to the recommendation service.

## Configuration Properties

Configurable types have child properties that are rendered into the UI in the order they display in the page. Property types define the inputs that are rendered. The following example defines a single text input box with the Title "Simple Property". Titles of form fields are automatically converted from camel case to title case.

```typescript
export class SimpleTemplate implements CampaignTemplate {
  simpleProperty: string;
}
```

![Simple Property](https://developer.salesforce.com/docs/media/interface-template-configuration/SimpleProperty.png)

<!-- document id=5f61b27e38f80c95f5208461f8811c8ab1393b8eab2854bac3c657e11be3e33d url=/developer/current/en-us/personalization/personalization/guides/data-analytics/data-dictionary.md -->

# Data Dictionary

## In This Article

- [Table campaign](#table-campaign)
- [Table category](#table-category)
- [Table country (deprecated)](#table-country-deprecated)
- [Table dimension](#table-dimension)
- [Table experience](#table-experience)
- [Table goal_completion_attribution](#table-goal_completion_attribution)
- [Table goal_completion_attribution_promoted_item](#table-goal_completion_attribution_promoted_item)
- [Table goal_completion_line_item](#table-goal_completion_line_item)
- [Table location (deprecated)](#table-location-deprecated)
- [Table order_line_item](#table-order_line_item)
- [Table order_line_item_attribute](#table-order_line_item_attribute)
- [Table product](#table-product)
- [Table product_attribute](#table-product_attribute)
- [Table product_category](#table-product_category)
- [Table product_dimension](#table-product_dimension)
- [Table segment](#table-segment)
- [Table segment_membership](#table-segment_membership)
- [Table survey_question (deprecated)](#table-survey_question-deprecated)
- [Table survey_response (deprecated)](#table-survey_response-deprecated)
- [Table user](#table-user)
- [Table user_alias](#table-user_alias)
- [Table user_attribute](#table-user_attribute)
- [Table user_campaign_state](#table-user_campaign_state)
- [Table user_click](#table-user_click)
- [Table user_daily_stat](#table-user_daily_stat)
- [Table user_daily_stat_action](#table-user_daily_stat_action)
- [Table user_daily_stat_item_stat_category](#table-user_daily_stat_item_stat_category)
- [Table user_daily_stat_item_stat_dimension](#table-user_daily_stat_item_stat_dimension)
- [Table user_daily_stat_item_stat_product](#table-user_daily_stat_item_stat_product)
- [Table user_daily_stat_item_stat_promotion](#table-user_daily_stat_item_stat_promotion)
- [Table user_dismissal](#table-user_dismissal)
- [Table user_engagement_history](#table-user_engagement_history)
- [Table user_goal_completion](#table-user_goal_completion)
- [Table user_impression](#table-user_impression)
- [Table user_order](#table-user_order)
- [Table user_order_attribute](#table-user_order_attribute)
- [Table user_search](#table-user_search)
- [Table user_user_visit_lookup](#table-user_user_visit_lookup)
- [Table user_visit](#table-user_visit)
- [Table user_visit_detail](#table-user_visit_detail)

## Table campaign

Campaigns contain experiences you design to personalize the interaction a visitor has with your website or application.

| Field Name          | Data Type                     | Description                                                | Example values                        |
| ------------------- | ----------------------------- | ---------------------------------------------------------- | ------------------------------------- |
| `id`                | `Char(5)`                     | Unique identifier for a campaign                           |                                       |
| `"type"`            | `Varchar(32)`                 | Campaign type implies marketing channel                    | `Web`, `MobileData`, `TriggeredEmail` |
| `created_ts`        | `Timestamp` without time zone | UTC date and time the campaign was created                 |                                       |
| `updated_ts`        | `Timestamp` without time zone | UTC date and time the campaign was most recently updated   |                                       |
| `last_published_ts` | `Timestamp` without time zone | UTC date and time the campaign was most recently published |                                       |
| `name`              | `Varchar(100)`                | Name of the campaign                                       |                                       |
| `state`             | `Varchar(100)`                | Campaign state                                             | `Published`, `Testing`, `Disabled`    |

### Indexes

- `PRIMARY KEY campaign_pkey ON campaign USING btree (id)`

### Referenced by

- `TABLE "experience" CONSTRAINT "experience_campaign_id_fkey" FOREIGN KEY (campaign_id) REFERENCES campaign(id)`
- `TABLE "user_campaign_state" CONSTRAINT "user_campaign_state_campaign_id_fkey" FOREIGN KEY (campaign_id) REFERENCES campaign(id)`

### Example Query

```sql
/* Find campaigns published in the recent 7 days */
SELECT id,
       name
FROM campaign
WHERE last_published_ts >= CURRENT_DATE - 7;
```

[Back to top](#in-this-article)

---

## Table category

In a hierarchical catalog, items belong to a category. This table stores the category IDs and names. In Personalization, there’s more than one way to represent a hierarchy. First, categories can be fully specified by the category ID itself (for example, `womensapparel|denim|highrise`). A hierarchy can be derived from the path. Second, you can use the `parent_id` field in the category. Products can belong to many categories. How you build categories depends on your integration, but the data structure supports both approaches.

Encoding the hierarchy in the ID is simpler. You can use the parent ID in cases where the hierarchy maybe unavailable, but the short, non-hierarchical ID remains consistent across channels and systems that reference categories.

| Field Name      | Data Type                     | Description                                                                                      | Example values |
| --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------ | -------------- |
| `id`            | `Varchar(200)`                | Unique identifier for the category                                                               |                |
| `name`          | `Varchar(200)`                | Name of the category                                                                             |                |
| `is_department` | `Boolean`                     | `true` when the category is a department (a higher-level entity in the category hierarchy)       |                |
| `parent_id`     | `Varchar(200)`                | Parent category ID of this category                                                              |                |
| `created_ts`    | `Timestamp` without time zone | Date and time the category was created in the operational store, UTC                             |                |
| `updated_ts`    | `Timestamp` without time zone | Date and time of the most recent update in the operation store, UTC (as of the recent DW import) |                |

### Indexes

- `PRIMARY KEY category_pkey ON category USING btree (id)`

### Referenced by

- `TABLE "product_category" CONSTRAINT "product_category_category_id_fkey" FOREIGN KEY (category_id) REFERENCES category(id)`
- `TABLE "user_daily_stat_item_stat_category" CONSTRAINT "user_daily_stat_item_stat_category_category_id_fkey" FOREIGN KEY (category_id) REFERENCES category(id)`

### Example Query

```sql
/* Get the number of products in each category */
SELECT c.name,
       count(1) AS num_products
FROM product_category pc
	     LEFT OUTER JOIN category c ON c.id = pc.category_id
GROUP BY 1
ORDER BY count(1) DESC
```

[Back to top](#in-this-article)

---

## Table country (deprecated)

**important:** The `country` dimension table is now deprecated and no longer in use.

Country lookup table. Provides `iso_2` and `iso_3` codes and continent information. For more information, refer to [IBAN's list of country ISO codes](https://www.iban.com/country-codes).

| Field Name             | Data Type                     | Description                                          | Example values                         |
| ---------------------- | ----------------------------- | ---------------------------------------------------- | -------------------------------------- |
| `id`                   | `Varchar(200)`                | Unique identifier for the country                    |                                        |
| `name`                 | `Varchar(100)`                | Name of the country                                  |                                        |
| `updated_ts`           | `Timestamp` without time zone | Date and time of the most recent update to the table |                                        |
| `iso_2_code`           | `Char(2)`                     | 2-character country code                             | `AW`, `GB`, `US`                       |
| `iso_3_code`           | `Char(3)`                     | 3-character country code                             | `ABW`, `GBR`                           |
| `has_regions`          | `Boolean`                     | True if the country has regions                      |                                        |
| `continent_code`       | `Varchar(100)`                | Numeric continent code                               | `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7` |
| `continent_iso_2_code` | `Char(2)`                     | ISO-2 standard code for a continent                  | `NA`, `AS`, `EU`                       |

### Indexes

- `PRIMARY KEY country_pkey ON country USING btree (id)`

### Example Query

```sql
/* count the number of visits by country */
SELECT c.name,
       count(1) as num_visits
FROM country c
	     LEFT OUTER JOIN user_visit_detail v ON c.id = v.country_code
GROUP BY 1
ORDER BY count(1) DESC;
```

[Back to top](#in-this-article)

---

## Table dimension

Dimensions are name-value pairs associated with items (usually products). Typical defaults are `brand`, `color`, `style`, and `gender`. Custom dimensions are also available. The combination of (`id`, `dimension_type`) is unique.

**note:** As of September 7, 2021, there’s no distinction between items and dimensions. They’re both now known and treated as catalog objects. For more information on catalog objects, refer to the [Catalog Objects documentation](https://developer.salesforce.com/docs/marketing/personalization/data-modeling/catalog.md#catalog-and-profile-objects).

| Field Name       | Data Type                     | Description                                                                                                  | Example values                      |
| ---------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
| `id`             | `Varchar(200)`                | Identifier for this dimension. The combination of `id` and `dimension_type` uniquely identifies a dimension. |                                     |
| `dimension_type` | `Varchar(200)`                | Built-in and custom types are supported. Dimension types are capitalized.                                    | `Brand`, `Gender`, `Color`, `Style` |
| `name`           | `Varchar(200)`                | The label used when displaying the dimension                                                                 | `Gucci`, `Mens`                     |
| `created_ts`     | `Timestamp` without time zone | Date and time the dimension was created                                                                      |                                     |
| `updated_ts`     | `Timestamp` without time zone | Date and time this dimension was most recently updated                                                       |                                     |

### Indexes

- `UNIQUE INDEX dimension_id_key ON dimension USING btree (id, dimension_type)`

### Referenced by

- `TABLE "product_dimension" CONSTRAINT "product_dimension_dimension_id_fkey" FOREIGN KEY (dimension_id, dimension_type) REFERENCES dimension(id, dimension_type)`

### Example Query

```sql
/* Get frequency and recency for stored dimension values */
SELECT dimension_type,
       count(1) AS num_names,
       max(updated_ts) AS most_recent_update
FROM dimension
GROUP BY 1;
```

[Back to top](#in-this-article)

---

## Table experience

Campaigns contain experiences. You can create different personalization results within the same campaign using experiences. Suppose you want to create a campaign for first-time visitors to your site. However, you want to show a different message to visitors from Boston and San Francisco where you have upcoming events. In this scenario, you would create 3 experiences in the same campaign: one campaign each for visitors from Boston and San Francisco, and one for everyone else. You can then use rules to restrict each experience's visibility to its respective target group.

| Field Name     | Data Type      | Description                               | Example values            |
| -------------- | -------------- | ----------------------------------------- | ------------------------- |
| `id`           | `Char(5)`      | Unique identifier for this experience     |                           |
| `name`         | `Varchar(100)` | Name of the experience                    |                           |
| `display_mode` | `Varchar(100)` | Presentation detail about the experience. | `Personalize`, `Redirect` |
| `campaign_id`  | `Char(5)`      | Associated Campaign ID                    |                           |

### Indexes

- `PRIMARY KEY experience_pkey ON experience USING btree (id)`

### Referenced by

- `TABLE "goal_completion_attribution" CONSTRAINT "goal_completion_attribution_experience_id_fkey" FOREIGN KEY (experience_id) REFERENCES experience(id)`
- `TABLE "goal_completion_attribution_promoted_item" CONSTRAINT "goal_completion_attribution_promoted_item_experience_id_fkey" FOREIGN KEY (experience_id) REFERENCES experience(id)`
- `TABLE "user_click" CONSTRAINT "user_click_experience_id_fkey" FOREIGN KEY (experience_id) REFERENCES experience(id)`
- `TABLE "user_dismissal" CONSTRAINT "user_dismissal_experience_id_fkey" FOREIGN KEY (experience_id) REFERENCES experience(id)`
- `TABLE "user_impression" CONSTRAINT "user_impression_experience_id_fkey" FOREIGN KEY (experience_id) REFERENCES experience(id)`

### Example Query

```sql
/* Get a list of campaigns and experiences that are published */
SELECT c.name AS campaign_name,
       e.name AS experience_name
FROM campaign c
	     INNER JOIN experience e ON c.id = e.campaign_id
WHERE c.state = 'Published';
```

[Back to top](#in-this-article)

---

## Table goal_completion_attribution

Stores the timestamp for the campaign goal in UTC. This table is important when reconstructing or analyzing campaign performance. Use the `last_age_seconds` field to decide whether to attribute a goal completion to a campaign.

| Field Name          | Data Type                     | Description                                                                                                        | Example values                                     |
| ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| `user_id`           | `Varchar(200`)                | User who satisfied the goal criteria                                                                               |                                                    |
| `goal_ts`           | `Timestamp` without time zone | Timestamp of the goal completion in UTC                                                                            |                                                    |
| `goal_id`           | `Varchar(256)`                | One of: segment id or purchase (p)                                                                                 | `p`                                                |
| `experience_id`     | `Varchar(256)`                | The experience associated with the goal completion                                                                 |                                                    |
| `user_group`        | `Char(1)`                     | Per experience test (D) and control (C)                                                                            | `C`, `D`                                           |
| `promotion_id`      | `Varchar(200)`                | The promotion associated with the goal completion                                                                  |                                                    |
| `direct_revenue`    | `Numeric(18,4`)               | Revenue associated with the promoted item of the goal                                                              |                                                    |
| `event_type`        | `Varchar(50)`                 | The event type                                                                                                     | `click`, `send`, `impression`                      |
| `first_age_seconds` | `Integer`                     | First age is the time between the first attributable event and the goal time.                                      |                                                    |
| `first_time_ts`     | `Timestamp` without time zone | Timestamp for the first attributable event, UTC                                                                    |                                                    |
| `last_age_seconds`  | `Integer`                     | Last age is the time between the most recent attributable event and the goal time.                                 |                                                    |
| `last_time_ts`      | `Timestamp` without time zone | Timestamp for the most recent attributable event, UTC                                                              |                                                    |
| `browser`           | `Varchar(256)`                | Client browser application                                                                                         | `Safari`, `Chrome`, `Firefox`, `IE`                |
| `device`            | `Varchar(256)`                | Client hardware device                                                                                             | `mobile`, computer, tablet, other                  |
| `engagement`        | `Varchar(256)`                | Engagement for the associated user                                                                                 | `low`, `medium`, `high`                            |
| `has_purchased`     | Boolean                       | Set when the user makes a purchase                                                                                 |                                                    |
| `is_anonymous`      | Boolean                       | `true` when the user isn’t named (identified)                                                                      |                                                    |
| `is_firsttime`      | Boolean                       | `true` when the completion represents a first encounter with a visitor                                             |                                                    |
| `os`                | `Varchar(256)`                | Operating system - x is "macOS X"                                                                                  | `x`, `windows`, `linux`, `ios`, `android`, `other` |
| `platform`          | `Varchar(256)`                | Platform used in the goal completion (email, web)                                                                  | `Email`, `Web`                                     |
| `source`            | `Varchar(256)`                | For web events, source is `Web`. For customers who use the mobile SDK, each mobile app would be a separate source. |                                                    |

### Indexes

- `UNIQUE INDEX goal_completion_attribution_user_id_key ON goal_completion_attribution USING btree (user_id, goal_id, goal_ts, experience_id, user_group, event_type)`

### Example Query

```sql
/* count the users eligible for goal completion with a 1-day window */

SELECT count(DISTINCT user_id)
FROM goal_completion_attribution
WHERE experience_id = '{EXPERIENCE_ID}'
	AND event_type = 'impression'
	AND last_age_seconds <= 60 * 60 * 24;
```

[Back to top](#in-this-article)

---

## Table goal_completion_attribution_promoted_item

If a goal completion has an associated promoted item, you can find it in this table. Use `(user_id, goal_id, goal_ts)` to join back to the other goal tables.

| Field Name      | Data Type                     | Description                                                                                                                                       | Example values |
| --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `user_id`       | `Varchar(200)`                | User associated with the goal completion                                                                                                          |                |
| `goal_ts`       | `Timestamp` without time zone | Timestamp of the goal completion in UTC                                                                                                           |                |
| `goal_id`       | `Varchar(256)`                | The goal id stores different value types; for segment goals, the goal id is the segment id; for purchase goals, the goal id is the character `p`. | `p`            |
| `experience_id` | `Varchar(256)`                | Experience associated with the goal                                                                                                               |                |
| `user_group`    | `Char(1)`                     | Per experience control (`C`) and test (`D`)                                                                                                       | `C`, `D`       |
| `item_id`       | `Varchar(256`)                | Unique identifier for the promoted item                                                                                                           |                |
| `item_type`     | `Varchar(256)`                | For example, `p` to indicate product                                                                                                              | `p`            |
| `attributes`    | `Varchar(256)`                | A list of attributes for the promoted item. The underlying data is JSON, stored here as a string.                                                 |                |
| `updated_ts`    | `Timestamp` without time zone | UTC Date and time of the most recent update of this promoted item attribution                                                                     |                |
| `revenue`       | `Numeric(18,4)`               | Revenue resulting from the goal completion                                                                                                        |                |

### Indexes

- `UNIQUE INDEX goal_completion_attribution_promoted_item_user_id_key ON goal_completion_attribution_promoted_item USING btree (user_id, goal_id, goal_ts, experience_id, user_group, item_type, item_id)`

### Example Query

```sql
/* Get total revenue, users, and products associated with goal completions for an experience */

SELECT sum(revenue) AS total_revenue,
       count(DISTINCT user_id) AS num_users,
       count(DISTINCT item_id) AS num_products
FROM goal_completion_attribution_promoted_item
WHERE experience_id = '{EXPERIENCE_ID}';
```

[Back to top](#in-this-article)

---

## Table goal_completion_line_item

For goal completions that are associated with a purchase, this table stores the line items associated with that purchase.

| Field Name      | Data Type                     | Description                                                                           | Example values |
| --------------- | ----------------------------- | ------------------------------------------------------------------------------------- | -------------- |
| `user_id`       | `Varchar(200)`                | User associated with the order                                                        |                |
| `goal_ts`       | `Timestamp` without time zone | Timestamp of the goal completion in UTC                                               |                |
| `goal_id`       | `Varchar(256)`                | `p` for purchase or a segment id                                                      | `p`            |
| `line_item_num` | `Smallint`                    | Data warehouse internal enumeration (doesn’t have an analog in the operational store) |                |
| `item_id`       | `Varchar(256)`                | Line item                                                                             |                |
| `item_type`     | `Varchar(256)`                | Typically `p` for product                                                             | `p`            |
| `price`         | `Numeric(18,4)`               | Item price                                                                            |                |
| `quantity`      | `Smallint`                    | Item quantity                                                                         |                |

### Indexes

- `UNIQUE INDEX goal_completion_line_item_user_id_key ON goal_completion_line_item USING btree (user_id, goal_id, goal_ts, line_item_num)`

### Example Query

```sql
/* average revenue per line item in goals */
SELECT avg(price * quantity)
FROM goal_completion_line_item;
```

[Back to top](#in-this-article)

---

## Table location (deprecated)

**important:** The `location` dimension table is now deprecated and no longer in use.

Use this table to de-reference geographical information stored at the visit or user level (for example, `city_code`, `metro_code`, `postal_code`, `latitude`, or `longitude`) and convert it to human-readable labels.

| Field Name       | Data Type                     | Description                                                                       | Example values         |
| ---------------- | ----------------------------- | --------------------------------------------------------------------------------- | ---------------------- |
| `id`             | `Varchar(200)`                | Unique identifier for the location                                                |                        |
| `latitude`       | `Numeric(9,6)`                | Latitude associated with the location                                             | `40.7134`, `37.0547`   |
| `longitude`      | `Numeric(9,6)`                | Longitude associated with the location                                            | `-111.889`, `-91.5281` |
| `postal_code`    | `Varchar(10)`                 | Postal code associated with the location                                          | `02143`                |
| `city_code`      | `Integer`                     | Code for the city associated with the location                                    |                        |
| `city_name`      | `Varchar(100)`                | Name of the city associated with the location                                     |                        |
| `metro_code`     | `Integer`                     | Metro code associated with the location. Metro codes for US are Nielsen DMA codes |                        |
| `region_code`    | `Varchar(10)`                 | Region code associated with the location                                          | `UT`, `WI`             |
| `country_code`   | `Varchar(100)`                | 2-letter Country code associated with the location                                | `US`, `IT`, `KR`       |
| `continent_code` | `Varchar(100)`                | 2-letter continent code associated with the location                              | `NA`, `SA`             |
| `updated_ts`     | `Timestamp` without time zone | UTC date and time of the most recent update to the location                       |                        |

### Indexes

- `PRIMARY KEY location_pkey ON "location" USING btree (id)`

[Back to top](#in-this-article)

---

## Table order_line_item

Stores the line items for a given order. Use `(user_id, order_id)` when joining back to order.

| Field Name         | Data Type                     | Description                                                                           | Example values |
| ------------------ | ----------------------------- | ------------------------------------------------------------------------------------- | -------------- |
| `user_id`          | `Varchar(200)`                | User id associated with the order                                                     |                |
| `order_id`         | `Varchar(256)`                | Unique identifier for the order associated with the line item                         |                |
| `line_item_num`    | `Smallint`                    | Data warehouse internal enumeration (doesn’t have an analog in the operational store) |                |
| `item_type`        | `Varchar(256)`                | Type of item. Usually product.                                                        |                |
| `item_id`          | `Varchar(256)`                | The item (usually product) associated with the order                                  |                |
| `price`            | `Numeric(18,4)`               | Unit price                                                                            |                |
| `quantity`         | `Smallint`                    | Item quantity for this line item                                                      |                |
| `currency`         | `Varchar(256)`                | Currency associated with the order                                                    |                |
| `sku`              | `Varchar(256)`                | Stock Keeping Unit associated with the line item                                      |                |
| `order_created_ts` | `Timestamp` without time zone | UTC date and time when the order was created                                          |                |

### Indexes

- `PRIMARY KEY order_line_item_pkey ON order_line_item USING btree (user_id, order_id, item_id, order_created_ts, line_item_num)`

[Back to top](#in-this-article)

---

## Table order_line_item_attribute

Provides attribute name-value pairs associated with line items, as well as provenance.

| Field Name                        | Data Type      | Description                                                                                                          | Example values                                                   |
| --------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `user_id`                         | `Varchar(200)` | User associated with the order                                                                                       |                                                                  |
| `order_id`                        | `Varchar(256)` | Unique order identifier                                                                                              |                                                                  |
| `line_item_num`                   | `Smallint`     | Generated in DW, a 1-based sequence value for this line item                                                         |                                                                  |
| `item_type`                       | `Varchar(256)` | Type type of item                                                                                                    |                                                                  |
| `item_id`                         | `Varchar(256)` | Unique identifier for the associated item                                                                            |                                                                  |
| `attribute_name`                  | `Varchar(256)` | The name of the attribute                                                                                            | `quantity_shipped`                                               |
| `attribute_value`                 | `Varchar(256)` | The value of the attribute                                                                                           |                                                                  |
| `value_metadata_origin`           | `Varchar(256`) | The name of the entity that issues or creates the initial attribute value.                                           | `CRM`, `PointOfSaleSystem`, `FulfillmentSystem`, `LoyaltySystem` |
| `value_metadata_provider`         | `Varchar(256)` | The name of the entity that is providing the attribute.                                                              | `CsvUserEtlJob:user-20190528.csv.gz`                             |
| `value_metadata_gear_id`          | `Varchar(256)` | ID of the Personalization gear that updated the attribute, or null if it wasn’t updated by a gear                    |                                                                  |
| `value_metadata_last_updated_ts`  | `Varchar(256)` | UTC date and time when the attribute was last updated                                                                |                                                                  |
| `value_metadata_last_verified_ts` | `Varchar(256)` | UTC date and time when the attribute value was last verified as being true and belonging to the specified individual |                                                                  |
| `value_metadata_classification`   | `Varchar(256)` | Metadata relevant or pertaining to the security classification of a given attribute's value                          |                                                                  |

### Indexes

- `PRIMARY KEY order_line_item_attribute_pkey ON order_line_item_attribute USING btree (user_id, order_id, item_type, item_id, line_item_num, attribute_name)`

[Back to top](#in-this-article)

---

## Table product

Stores product name and price.

| Field Name        | Data Type                     | Description                                                                           | Example values            |
| ----------------- | ----------------------------- | ------------------------------------------------------------------------------------- | ------------------------- |
| `id`              | `Varchar(200)`                | Unique identifier for the product                                                     |                           |
| `name`            | `Varchar(200)`                | Name of the product                                                                   |                           |
| `description`     | `Varchar(500)`                | Description of the product                                                            |                           |
| `list_price`      | `Real`                        | The list price of the product                                                         |                           |
| `price`           | `Real`                        | Unit price displayed to an anonymous user when promoting the product                  |                           |
| `created_ts`      | `Timestamp` without time zone | UTC date and time the product created in Personalization system                       |                           |
| `updated_ts`      | `Timestamp` without time zone | UTC date and time the product was most recently updated in the Personalization system |                           |
| `promotion_state` | `Varchar(50)`                 | Metadata concerning product eligibility and prioritization                            | `Excluded`, `Prioritized` |
| `url`             | `Varchar(2048)`               | URL for the product                                                                   |                           |
| `image_url`       | `Varchar(2048)`               | URL for the product image                                                             |                           |

### Indexes

- `PRIMARY KEY product_pkey ON product USING btree (id)`

### Referenced by

- `TABLE "product_attribute" CONSTRAINT "product_attribute_product_id_fkey" FOREIGN KEY (product_id) REFERENCES product(id)`
- `TABLE "product_category" CONSTRAINT "product_category_product_id_fkey" FOREIGN KEY (product_id) REFERENCES product(id)`
- `TABLE "product_dimension" CONSTRAINT "product_dimension_product_id_fkey" FOREIGN KEY (product_id) REFERENCES product(id)`
- `TABLE "user_daily_stat_item_stat_product" CONSTRAINT "user_daily_stat_item_stat_product_product_id_fkey" FOREIGN KEY (product_id) REFERENCES product(id)`

[Back to top](#in-this-article)

---

## Table product_attribute

Stores [attribute data](https://developer.salesforce.com/docs/marketing/personalization/data-modeling/attributes.md) about products, as well as provenance for the attributed value.

| Field Name                        | Data Type      | Description                                                                                                          | Example values                                                   |
| --------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `product_id`                      | `Varchar(200)` | Unique identifier for the product                                                                                    |                                                                  |
| `attribute_name`                  | `Varchar(256)` | The name of the attribute                                                                                            |                                                                  |
| `attribute_value`                 | `Varchar(256)` | The value of the attribute                                                                                           |                                                                  |
| `value_metadata_origin`           | `Varchar(256)` | The name of the entity that issues or creates the initial attribute value                                            | `CRM`, `PointOfSaleSystem`, `FulfillmentSystem`, `LoyaltySystem` |
| `value_metadata_provider`         | `Varchar(256)` | The name of the entity that is providing the attribute                                                               | `CsvUserEtlJob:user-20190528.csv.gz`                             |
| `value_metadata_gear_id`          | `Varchar(256)` | ID of the Personalization gear that updated the attribute, or `null` if it wasn’t updated by a gear                  |                                                                  |
| `value_metadata_last_updated_ts`  | `Varchar(256`) | UTC date and time when the attribute was last updated                                                                |                                                                  |
| `value_metadata_last_verified_ts` | `Varchar(256)` | UTC date and time when the attribute value was last verified as being true and belonging to the specified individual |                                                                  |
| `value_metadata_classification`   | `Varchar(256)` | Metadata relevant or pertaining to the security classification of a given attribute's value                          |                                                                  |

### Indexes

- `PRIMARY KEY product_attribute_pkey ON product_attribute USING btree (product_id, attribute_name)`

[Back to top](#in-this-article)

---

## Table product_category

A product can belong to more than one (fully qualified) category. This table stores product-category relationships.

| Field Name    | Data Type      | Description                        | Example values |
| ------------- | -------------- | ---------------------------------- | -------------- |
| `product_id`  | `Varchar(256)` | Unique identifier for the product  |                |
| `category_id` | `Varchar(256)` | Unique identifier for the category |                |

### Indexes

- `UNIQUE INDEX product_category_product_id_key ON product_category USING btree (product_id, category_id)`

[Back to top](#in-this-article)

---

## Table product_dimension

Logically the (`dimension_type`, `dimension_id`) are a name-value pair associated with a product. Common dimensions include gender, brand, and style. Custom dimensions are also available.

| Field Name       | Data Type      | Description                                              | Example values             |
| ---------------- | -------------- | -------------------------------------------------------- | -------------------------- |
| `product_id`     | `Varchar(200)` | Unique identifier for a product                          |                            |
| `dimension_id`   | `Varchar(200)` | The value of a dimension                                 | `Gucci`, `Red`             |
| `dimension_type` | `Varchar(200)` | The name of a dimension. Dimension names are capitalized | `Brand`, `Gender`, `Style` |

### Indexes

- `UNIQUE INDEX product_dimension_product_id_key ON product_dimension USING btree (product_id, dimension_type, dimension_id)`

[Back to top](#in-this-article)

---

## Table segment

A Personalization segment is a real-time grouping of accounts or individuals based on a set of criteria you define. Segment updates in the operational store happen in real time, so any membership changes occur immediately, even during the same visit. Exports to this table, if done at all, are done one time per day. Segment export is enabled for individual segments by request, on the condition that the segment is small enough to export in this manner.

| Field Name    | Data Type                     | Description                                     | Example values    |
| ------------- | ----------------------------- | ----------------------------------------------- | ----------------- |
| `id`          | `Varchar(10)`                 | Unique identifier for the segment               |                   |
| `name`        | `Varchar(200)`                | Name of the segment                             |                   |
| `is_goal`     | `Boolean`                     | `true` when segment is associated with a goal.  |                   |
| `entity_type` | `Varchar(200)`                | The type of entity associated with this segment | `Account`, `User` |
| `created_ts`  | `Timestamp` without time zone | UTC date and time of creation                   |                   |
| `updated_ts`  | `Timestamp` without time zone | UTC date and time of recent update              |                   |

### Indexes

- `PRIMARY KEY segment_pkey ON segment USING btree (id)`

### Referenced by

- `TABLE "segment_membership" CONSTRAINT "segment_membership_segment_id_fkey" FOREIGN KEY (segment_id) REFERENCES segment(id)`

[Back to top](#in-this-article)

---

## Table segment_membership

User-segment associations. For B2C, segments are associated with users.

| Field Name   | Data Type                     | Description                                                                                                              | Example values |
| ------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------- |
| `user_id`    | `Varchar(200)`                | Segment member                                                                                                           |                |
| `segment_id` | `Varchar(200)`                | Unique identifier for the segment                                                                                        |                |
| `joined_ts`  | `Timestamp` without time zone | UTC date and time of segment join event                                                                                  |                |
| `left_ts`    | `Timestamp` without time zone | UTC date and time of segment leave event. **Note:** This field is never populated and its value is always set to `NULL`. |                |
| `is_active`  | `Boolean`                     | True if user is an active member of the segment                                                                          |                |
| `updated_dt` | `Timestamp` without time zone | UTC date and time of most recent update                                                                                  |                |

### Indexes

- `UNIQUE INDEX segment_membership_user_id_key ON segment_membership USING btree (user_id, segment_id, joined_ts)`

[Back to top](#in-this-article)

---

## Table survey_question (deprecated)

**important:** The `survey_question` dimension table is now deprecated and no longer in use.

Survey questions and associated metadata

| Field Name          | Data Type                     | Description                                                                  | Example values |
| ------------------- | ----------------------------- | ---------------------------------------------------------------------------- | -------------- |
| `survey_id`         | `Varchar(6)`                  | Unique identifier for the survey                                             |                |
| `survey_name`       | `Varchar(200)`                | Name of the survey                                                           |                |
| `survey_updated_ts` | `Timestamp` without time zone | UTC date and time of the most recent update to the question                  |                |
| `page_name`         | `Varchar(200)`                | Page name on which the question appears                                      |                |
| `page_num`          | `Integer`                     | Internal sequence number for the page                                        |                |
| `element_name`      | `Varchar(200)`                | Name of the element in which the question appears. Pages have many elements. |                |
| `element_title`     | `Varchar(200)`                | Title of the element in which the question appears                           |                |
| `element_type`      | `Varchar(200)`                | The type of element - text, radio button, and so on.                         |                |
| `element_id`        | `Varchar(200)`                | Unique identifier for the element in which the question appears              |                |
| `element_num`       | `Integer`                     | Internal sequence enumerating the elements on a page                         |                |
| `question_id`       | `Varchar(200)`                | Unique identifier for the question                                           |                |

### Indexes

- `UNIQUE INDEX survey_question_survey_id_key ON survey_question USING btree (survey_id, question_id, element_id, page_num, element_num)`

[Back to top](#in-this-article)

---

## Table survey_response (deprecated)

**important:** The `survey_response` dimension table is now deprecated and no longer in use.

| Field Name       | Data Type                     | Description                                                                                 | Example values |
| ---------------- | ----------------------------- | ------------------------------------------------------------------------------------------- | -------------- |
| `survey_id`      | `Varchar(6)`                  | Unique identifier for the survey                                                            |                |
| `started_ts`     | `Timestamp` without time zone | UTC date and time the survey was started                                                    |                |
| `user_id`        | `Varchar(200)`                | Unique identifier for the user taking the survey                                            |                |
| `question_id`    | `Varchar(200)`                | Unique identifier for the survey question                                                   |                |
| `survey_session` | `Varchar(200)`                | hash of `survey_id`, `started_ts`, `user_id`, which can help group questions into a session |                |
| `response_ts`    | `Timestamp` without time zone | UTC date and time the response was made                                                     |                |
| `answer`         | `Varchar(2048)`               | Long text field that captures the survey answer                                             |                |

### Indexes

- `UNIQUE INDEX survey_response_user_id_key ON survey_response USING btree (user_id, survey_id, question_id, response_ts)`

[Back to top](#in-this-article)

---

## Table user

User is the center of the Personalization data model. Much of the data about users is stored in tables other than this one; this table stores top-level information associated with a user. Fields prefixed with `loc_` refer to location information. Location codes can be looked up in the Location table. Fields prefixed with `or_` refer to the original referring event for this user.

| Field Name                      | Data Type                     | Description                                                                                                                                                                                                                                                               | Example values                                        |
| ------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `id`                            | `Varchar(200)`                | Unique id for the user                                                                                                                                                                                                                                                    |                                                       |
| `id_mod_100`                    | `Integer`                     | An offset from 0 to 99 used to create random partitions in the audience                                                                                                                                                                                                   |                                                       |
| `first_activity_ts`             | `Timestamp` without time zone | UTC date and time the user was first observed                                                                                                                                                                                                                             |                                                       |
| `last_activity_ts`              | `Timestamp` without time zone | UTC date and time the user was most recently observed                                                                                                                                                                                                                     |                                                       |
| `engagement_score`              | `Integer`                     | The engagement score is an index that tracks how engaged your site visitors and application users are based on several different factors including visit information, actions, key performance indicators (KPIs), and segments. Higher values indicate deeper engagement. |                                                       |
| `engagement_dt`                 | `Date`                        | The time the engagement score was computed.                                                                                                                                                                                                                               |                                                       |
| `created_ts`                    | `Timestamp` without time zone | UTC date and time this record was created                                                                                                                                                                                                                                 |                                                       |
| `loc_device_provided`           | `Boolean`                     | `true` if the location (`loc_` fields) was provided by a device (for example, obtained via a GPS retrieval), or `false` if this location is an approximate determined via geocoding of an IP address                                                                      |                                                       |
| `loc_ip_address`                | `Varchar(100)`                | IP Address associated with the user location                                                                                                                                                                                                                              |                                                       |
| `loc_continent_key`             | `Varchar(100)`                | 2-letter continent code associated with the user location                                                                                                                                                                                                                 | `NA`, `AS`                                            |
| `loc_country_code`              | `Char(2)`                     | An [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (for example, `US`)                                                                                                                                                                 | `US`                                                  |
| `loc_country_numeric_code`      | `Smallint`                    | ISO-3166-1 numeric country code (for example, `840` for United States)                                                                                                                                                                                                    |                                                       |
| `loc_region_code`               | `Integer`                     | Location's region code. Note - doesn’t correspond to `location(region_code)`                                                                                                                                                                                              |                                                       |
| `loc_metro_code`                | `Integer`                     | Location's metro code, corresponds to `location(metro_code)`. For the US, the metro code is the Nielsen Designated Market Area (DMA) code                                                                                                                                 |                                                       |
| `loc_city_code`                 | `Integer`                     | Location's city code, corresponds to `location(city_code)`                                                                                                                                                                                                                |                                                       |
| `loc_postal_code`               | `Varchar(10)`                 | Location's postal code                                                                                                                                                                                                                                                    |                                                       |
| `loc_isp`                       | `Varchar(100)`                | Internet Service Provider associated with a location                                                                                                                                                                                                                      | `Telstra Internet`, `Comcast`, `Verizon`              |
| `loc_organization`              | `Varchar(100)`                | Organization associated with a location (can be `null`)                                                                                                                                                                                                                   |                                                       |
| `loc_naics_code`                | `Integer`                     | NAICS industry code                                                                                                                                                                                                                                                       |                                                       |
| `or_medium`                     | `Varchar(50)`                 | Original referrer medium - how the user first arrived                                                                                                                                                                                                                     | `SEARCH`, `EMAIL`, `SOCIAL`, `DIRECT`                 |
| `or_referrer_source`            | `Varchar(50)`                 | Source of the original referrer                                                                                                                                                                                                                                           | `Google`, `Bing`, `Yahoo!`, `Facebook`, `Pinterest`   |
| `or_query_terms`                | `Varchar(512)`                | Search terms for user who first arrived via search                                                                                                                                                                                                                        |                                                       |
| `or_referrer_domain`            | `Varchar(100)`                | Domain of the original referrer                                                                                                                                                                                                                                           | `google.com`, `bing.com`, `google.de`, `facebook.com` |
| `or_referrer_reverse_subdomain` | `Varchar(200)`                | Full host associated with the original referrer, reversed Used operationally                                                                                                                                                                                              | `mx.com.google.www`                                   |
| `is_anonymous`                  | `Boolean`                     | `true` when this user isn’t identifiable                                                                                                                                                                                                                                  |                                                       |
| `lifetime_value`                | `Real`                        | Total amount this user has spent                                                                                                                                                                                                                                          |                                                       |
| `loc_city`                      | `Varchar(256)`                | City name associated with the user's most recent location                                                                                                                                                                                                                 |                                                       |
| `loc_latitude`                  | `Real`                        | Latitude associated with the user's most recent location                                                                                                                                                                                                                  |                                                       |
| `loc_longitude`                 | `Real`                        | Longitude associated with the user's most recent location                                                                                                                                                                                                                 |                                                       |
| `loc_timezone`                  | `Varchar(256)`                | Timezone associated with the user's most recent location                                                                                                                                                                                                                  |                                                       |
| `updated_ts`                    | `Timestamp` without time zone | UTC date and time the user was most recently updated                                                                                                                                                                                                                      |                                                       |
| `loc_state_province_code`       | `Varchar(256)`                | Alphanumeric code associated with the user's most recent location                                                                                                                                                                                                         | `KY`, `PAC`                                           |
| `or_referring_url`              | `Varchar(2048)`               | URL associated with the original referrer                                                                                                                                                                                                                                 | `https://www.google.com/`                             |
| `or_landing_url`                | `Varchar(2048)`               | URL of the first page the user saw                                                                                                                                                                                                                                        |                                                       |
| `email_address`                 | `Varchar(100)`                | Email address associated with the user, if available                                                                                                                                                                                                                      |                                                       |

### Indexes

- `PRIMARY KEY user_pkey ON "user" USING btree (id)`

### Referenced by

- `TABLE "goal_completion_attribution_promoted_item" CONSTRAINT "goal_completion_attribution_promoted_item_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "goal_completion_attribution" CONSTRAINT "goal_completion_attribution_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "goal_completion_line_item" CONSTRAINT "goal_completion_line_item_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "order_line_item_attribute" CONSTRAINT "order_line_item_attribute_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "order_line_item" CONSTRAINT "order_line_item_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "segment_membership" CONSTRAINT "segment_membership_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_alias" CONSTRAINT "user_alias_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_attribute" CONSTRAINT "user_attribute_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_campaign_state" CONSTRAINT "user_campaign_state_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_click" CONSTRAINT "user_click_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_daily_stat_action" CONSTRAINT "user_daily_stat_action_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_daily_stat_item_stat_category" CONSTRAINT "user_daily_stat_item_stat_category_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_daily_stat_item_stat_dimension" CONSTRAINT "user_daily_stat_item_stat_dimension_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_daily_stat_item_stat_product" CONSTRAINT "user_daily_stat_item_stat_product_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_daily_stat_item_stat_promotion" CONSTRAINT "user_daily_stat_item_stat_promotion_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_daily_stat" CONSTRAINT "user_daily_stat_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_dismissal" CONSTRAINT "user_dismissal_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_engagement_history" CONSTRAINT "user_engagement_history_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_goal_completion" CONSTRAINT "user_goal_completion_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_impression" CONSTRAINT "user_impression_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_order_attribute" CONSTRAINT "user_order_attribute_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_order" CONSTRAINT "user_order_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_search" CONSTRAINT "user_search_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`
- `TABLE "user_visit" CONSTRAINT "user_visit_user_id_fkey" FOREIGN KEY (user_id) REFERENCES "user"(id)`

[Back to top](#in-this-article)

---

## Table user_alias

This table contains the IDs of any anonymous users that have been merged into a given user. It also contains any non-anonymous IDs they used to have. This occurs when userIDs are changed to a new format, or simply a new ID.

| Field Name   | Data Type      | Description                       | Example values |
| ------------ | -------------- | --------------------------------- | -------------- |
| `user_id`    | `Varchar(200)` | Unique identifier for a user      |                |
| `anon_alias` | `Varchar(200)` | User Id associated with this user |                |

### Indexes

- `UNIQUE INDEX user_alias_user_id_key ON user_alias USING btree (user_id, anon_alias)`

[Back to top](#in-this-article)

---

## Table user_attribute

Name-value pairs associated with a user (many different use cases - ids, segment support, and so on)

| Field Name   | Data Type                     | Description                                                | Example values |
| ------------ | ----------------------------- | ---------------------------------------------------------- | -------------- |
| `user_id`    | `Varchar(200)`                | Unique identifier for the user                             |                |
| `updated_ts` | `Timestamp` without time zone | UTC date and time this attribute was most recently updated |                |
| `name`       | `Varchar(256)`                | Name of the attribute                                      |                |
| `value`      | `Varchar(256)`                | Value of the attribute                                     |                |

### Indexes

- `PRIMARY KEY user_attribute_pkey ON user_attribute USING btree (user_id, name, updated_ts)`

[Back to top](#in-this-article)

---

## Table user_campaign_state

This table provides summary information about a user or campaign. It mirrors the current state of an operational table for real-time reporting or other application. Although this table is less useful in a warehouse context, it does provide the state at batch time. You can use this table to quickly confirm membership or perform other on-demand tasks that can later be migrated to fully fleshed-out queries.

| Field Name            | Data Type                     | Description                                                             | Example values |
| --------------------- | ----------------------------- | ----------------------------------------------------------------------- | -------------- |
| `user_id`             | `Varchar(200)`                | Unique identifier for the user                                          |                |
| `campaign_id`         | `Varchar(256)`                | Unique identifier for the campaign                                      |                |
| `last_reset_time_ts`  | `Timestamp` without time zone | UTC date and time of the most recent campaign reset                     |                |
| `experience_id`       | `Varchar(256)`                | Unique identifier for the experience                                    |                |
| `user_group`          | `Varchar(256)`                | The user group (control or test) associated with this user's experience |                |
| `num_clicks`          | `Integer`                     | Total number of clicks                                                  |                |
| `first_click_ts`      | `Timestamp` without time zone | UTC date and time of the least recent click                             |                |
| `last_click_ts`       | `Timestamp` without time zone | UTC date and time of the most recent click                              |                |
| `num_impressions`     | `Integer`                     | Total number of impressions                                             |                |
| `first_impression_ts` | `Timestamp` without time zone | UTC date and time of the least recent impression                        |                |
| `last_impression_ts`  | `Timestamp` without time zone | UTC date and time of the most recent impression                         |                |

### Indexes

- `UNIQUE INDEX user_campaign_state_user_id_key ON user_campaign_state USING btree (user_id, campaign_id, experience_id, user_group)`

[Back to top](#in-this-article)

---

## Table user_click

Stores click events associated with a campaign at the visit level. `Event_ts` is associated with the most recent event.

| Field Name      | Data Type                     | Description                                                                                | Example values                                     |
| --------------- | ----------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| `user_id`       | `Varchar(200)`                | Unique identifier for the user                                                             |                                                    |
| `experience_id` | `Varchar(256)`                | Unique identifier for the experience                                                       |                                                    |
| `event_ts`      | `Timestamp` without time zone | UTC date and time of the most recent click in a session                                    |                                                    |
| `user_group`    | `Char(1)`                     | The user group associated with the user and experience - control (`C`) or test (`D`)       |                                                    |
| `browser`       | `Varchar(256)`                | Client browser application                                                                 | `Safari`, `Chrome`, `Firefox`, `IE`, `other`       |
| `device`        | `Varchar(256)`                | Client hardware device                                                                     | `mobile`, `computer`, `tablet`, `other`            |
| `engagement`    | `Varchar(256)`                | Engagement for the associated user                                                         | `low`, `medium`, `high`                            |
| `has_purchased` | `Boolean`                     | Set when the user makes a purchase                                                         |                                                    |
| `click_count`   | `Smallint`                    | Total number of clicks for the session                                                     |                                                    |
| `is_anonymous`  | `Boolean`                     | `true` when the user isn’t named (identified)                                              |                                                    |
| `is_firsttime`  | `Boolean`                     | `true` when this visit is a user's first                                                   |                                                    |
| `os`            | `Varchar(256)`                | Operating system - `x` is "macOS X"                                                        | `x`, `windows`, `linux`, `ios`, `android`, `other` |
| `platform`      | `Varchar(256)`                | Platform associated with the clicks                                                        | `Email`, `Web`                                     |
| `source`        | `Varchar(256)`                | For customers who use the mobile SDK, each mobile app would be listed as a separate source |                                                    |

### Indexes

- `PRIMARY KEY user_click_pkey ON user_click USING btree (user_id, experience_id, event_ts)`

[Back to top](#in-this-article)

---

## Table user_daily_stat

Aggregation of events at the (user, day) grain

| Field Name      | Data Type      | Description                                     | Example values |
| --------------- | -------------- | ----------------------------------------------- | -------------- |
| `stat_date`     | `Date`         | Date of the stat aggregation for this user      |                |
| `user_id`       | `Varchar(200)` | Unique identifier for the user                  |                |
| `visit_count`   | `Integer`      | Number of times user visited on the `stat_date` |                |
| `visit_millis`  | `Bigint`       | Total visit duration, in milliseconds           |                |
| `total_actions` | `Integer`      | Number of actions performed by the user         |                |
| `num_pages`     | `Integer`      | Number of pages the user viewed                 |                |

### Indexes

- `UNIQUE INDEX user_daily_stat_stat_date_key ON user_daily_stat USING btree (stat_date, user_id)`

[Back to top](#in-this-article)

---

## Table user_daily_stat_action

Aggregation of events at the (user, day, action) grain

| Field Name     | Data Type      | Description                                                               | Example values                                    |
| -------------- | -------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
| `stat_date`    | `Date`         | Date of the stat aggregation for this user                                |                                                   |
| `user_id`      | `Varchar(200)` | Unique identifier for the user                                            |                                                   |
| `action_id`    | `Varchar(200)` | Identifier for an action performed by the user                            | `Home`, `Search`, `View Category`, `View Product` |
| `action_count` | `Integer`      | Total count of actions for this action on this day by the associated user |                                                   |

### Indexes

- `UNIQUE INDEX user_daily_stat_action_stat_date_key ON user_daily_stat_action USING btree (stat_date, user_id, action_id)`

[Back to top](#in-this-article)

---

## Table user_daily_stat_item_stat_category

Aggregation of events at the (user, day, product category) grain

| Field Name           | Data Type       | Description                                                   | Example values |
| -------------------- | --------------- | ------------------------------------------------------------- | -------------- |
| `stat_date`          | `Date`          | Date associated with the stat                                 |                |
| `user_id`            | `Varchar(200)`  | Unique identifier for the user                                |                |
| `category_id`        | `Varchar(200)`  | Unique identifier for the category                            |                |
| `cart_value`         | `Numeric(18,4)` | Total value of items in the cart for this day, category, user |                |
| `num_cart_items`     | `Integer`       | Count of items in the cart                                    |                |
| `num_purchases`      | `Integer`       | Count of purchases                                            |                |
| `out_of_stock_views` | `Integer`       | Count of views of products that were out of stock             |                |
| `purchase_value`     | `Numeric(18,4)` | Total value of purchased made for this user, category, date   |                |
| `recommended_count`  | `Integer`       | Number of items recommended to the user for this category     |                |
| `view_time_millis`   | `Integer`       | Total view time for the category in milliseconds              |                |
| `view_value`         | `Numeric(18,4)` | The sum of the value of items viewed in this category         |                |
| `views`              | `Integer`       | Number of views for this category, day, user                  |                |

### Indexes

- `UNIQUE INDEX user_daily_stat_item_stat_category_stat_date_key ON user_daily_stat_item_stat_category USING btree (stat_date, user_id, category_id)`

[Back to top](#in-this-article)

---

## Table user_daily_stat_item_stat_dimension

Aggregation of events at the (user, day, product dimension) grain

| Field Name           | Data Type       | Description                                                    | Example values                          |
| -------------------- | --------------- | -------------------------------------------------------------- | --------------------------------------- |
| `stat_date`          | `Date`          | Date associated with the stat                                  |                                         |
| `user_id`            | `Varchar(200)`  | Unique identifier for the user                                 |                                         |
| `dimension_type`     | `Varchar(256)`  | The name of a dimension. Dimension names are capitalized.      | `Brand`, `Gender`, `Style`, `ItemClass` |
| `dimension_id`       | `Varchar(256)`  | Unique identifier for the dimension                            |                                         |
| `cart_value`         | `Numeric(18,4)` | Total value of items in the cart for this day, dimension, user |                                         |
| `num_cart_items`     | `Integer`       | Count of items in the cart                                     |                                         |
| `num_purchases`      | `Integer`       | Count of purchases                                             |                                         |
| `out_of_stock_views` | `Integer`       | Count of views of products that were out of stock              |                                         |
| `purchase_value`     | `Numeric(18,4)` | Total value of purchased made for this user, dimension, date   |                                         |
| `recommended_count`  | `Integer`       | Number of items recommended to the user for this dimension     |                                         |
| `view_time_millis`   | `Integer`       | Total view time for the dimension in milliseconds              |                                         |
| `view_value`         | `Numeric(18,4)` | The sum of the value of items viewed in this dimension         |                                         |
| `views`              | `Integer`       | Number of views for this dimension, day, user                  |                                         |

### Indexes

- `UNIQUE INDEX user_daily_stat_item_stat_dimension_stat_date_key ON user_daily_stat_item_stat_dimension USING btree (stat_date, user_id, dimension_type, dimension_id)`

[Back to top](#in-this-article)

---

## Table user_daily_stat_item_stat_product

Aggregation of events at the (user, day, product) grain

| Field Name           | Data Type       | Description                                                  | Example values |
| -------------------- | --------------- | ------------------------------------------------------------ | -------------- |
| `stat_date`          | `Date`          | Date associated with the stat                                |                |
| `user_id`            | `Varchar(200)`  | Unique identifier for the user                               |                |
| `product_id`         | `Varchar(200)`  | Unique identifier for the product                            |                |
| `cart_value`         | `Numeric(18,4)` | Total value of items in the cart for this day, product, user |                |
| `num_cart_items`     | `Integer`       | Count of items in the cart                                   |                |
| `num_purchases`      | `Integer`       | Count of purchases                                           |                |
| `out_of_stock_views` | `Integer`       | Count of views of products that were out of stock            |                |
| `purchase_value`     | `Numeric(18,4)` | Total value of purchased made for this user, product, date   |                |
| `recommended_count`  | `Integer`       | Number of items recommended to the user for this product     |                |
| `view_time_millis`   | `Integer`       | Total view time for the product in milliseconds              |                |
| `view_value`         | `Numeric(18,4)` | The sum of the value of items viewed in this product         |                |
| `views`              | `Integer`       | Number of views for this product, day, user                  |                |

### Indexes

- `UNIQUE INDEX user_daily_stat_item_stat_product_stat_date_key ON user_daily_stat_item_stat_product USING btree (stat_date, user_id, product_id)`

### Example Query

```sql
/* top products using daily stats */
SELECT
	CASE WHEN pct_total > 1
		     THEN a.name
	     ELSE 'ALL OTHERS' END                          AS name,
	to_char(sum(revenue), 'FM$999,999,999,990D00') AS revenue,
	to_char(sum(pct_total), 'FM99.99%')            AS pct_total,
	sum(rnk)                                          rnk
FROM
	(
		SELECT
			p.name,
			sum(a.num_purchases * purchase_value) revenue,
			ratio_to_report(sum(a.num_purchases * purchase_value))
			OVER () * 100             AS          pct_total,
			row_number()
			OVER (
				ORDER BY revenue DESC ) AS          rnk
		FROM
			product p,
			user_daily_stat_item_stat_product a
		WHERE
				p.id = a.product_id
		GROUP BY 1
		ORDER BY sum(a.num_purchases * purchase_value) DESC
	) a
GROUP BY 1
ORDER BY rnk
```

[Back to top](#in-this-article)

---

## Table user_daily_stat_item_stat_promotion

Aggregation of events at the (user, day, promotion) grain

| Field Name              | Data Type       | Description                                                          | Example values |
| ----------------------- | --------------- | -------------------------------------------------------------------- | -------------- |
| `stat_date`             | `Date`          | Date for the stat                                                    |                |
| `user_id`               | `Varchar(200)`  | Unique identifier for the user                                       |                |
| `promotion_id`          | `Varchar(200)`  | Unique identifier for the promotion                                  |                |
| `cart_value`            | `Numeric(18,4)` | Total value of items in the cart for this day, promotion, user       |                |
| `num_cart_items`        | `Integer`       | Count of items in the cart                                           |                |
| `num_purchases`         | `Integer`       | Count of purchases                                                   |                |
| `out_of_stock_views`    | `Integer`       | Count of views of promotions associated with an out of stock product |                |
| `purchase_value`        | `Numeric(18,4)` | Total value of purchases made for this user, promotion, date         |                |
| `recommended_count`     | `Integer`       | Number of items recommended to the user for this promotion           |                |
| `view_time_millis`      | `Integer`       | Total view time for the promotion in milliseconds                    |                |
| `view_value`            | `Numeric(18,4)` | The sum of the value of promotions viewed                            |                |
| `views`                 | `Integer`       | Number of views by this user for this promotion and day              |                |
| `eligible_for_serving`  | `Integer`       | Number of times this promotion was eligible to be served             |                |
| `requested_for_serving` | `Integer`       | Number of times this promotion was requested to be served            |                |
| `served`                | `Integer`       | Number of times this promotion was served                            |                |

### Indexes

- `UNIQUE INDEX user_daily_stat_item_stat_promotion_stat_date_key ON user_daily_stat_item_stat_promotion USING btree (stat_date, user_id, promotion_id)`

[Back to top](#in-this-article)

---

## Table user_dismissal

Stores dismissal events associated with a campaign at the visit level. Event_ts is associated with the most recent event.

| Field Name        | Data Type                     | Description                                                                       | Example values                                     |
| ----------------- | ----------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------- |
| `user_id`         | `Varchar(200)`                | Unique identifier for the user                                                    |                                                    |
| `experience_id`   | `Varchar(256)`                | Unique identifier for the experience                                              |                                                    |
| `event_ts`        | `Timestamp` without time zone | UTC date and time of the most recent dismissal in a session.                      |                                                    |
| `user_group`      | `Char(1)`                     | The user group associated with the user and experience - control (`C`) or (`D`)   |                                                    |
| `browser`         | `Varchar(256)`                | Client browser application                                                        | `Safari`, `Chrome`, `Firefox`, `IE`, `other`       |
| `device`          | `Varchar(256)`                | Client hardware device                                                            | `mobile`, `computer`, `tablet`, `other`            |
| `engagement`      | `Varchar(256)`                | Engagement for the associated user                                                | `low`, `medium`, `high`                            |
| `has_purchased`   | `Boolean`                     | Set when the user makes a purchase                                                |                                                    |
| `dismissal_count` | `Smallint`                    | Total number of dismissals for the session                                        |                                                    |
| `is_anonymous`    | `Boolean`                     | `true` when the user isn’t named (identified)                                     |                                                    |
| `is_firsttime`    | `Boolean`                     | `true` when this visit is a user's first                                          |                                                    |
| `os`              | `Varchar(256)`                | Operating system - x is "macOS X"                                                 | `x`, `windows`, `linux`, `ios`, `android`, `other` |
| `platform`        | `Varchar(256)`                | Platform associated with the dismissals                                           | `Email`, `Web`                                     |
| `source`          | `Varchar(256)`                | For customers who use the mobile SDK, each mobile app would be a separate source. |                                                    |

### Indexes

- `PRIMARY KEY user_dismissal_pkey ON user_dismissal USING btree (user_id, experience_id, event_ts)`

[Back to top](#in-this-article)

---

## Table user_engagement_history

Stores historical engagement values at the user grain

| Field Name | Data Type      | Description                                                                                                                                                                                                                                      | Example values |
| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| `user_id`  | `Varchar(200)` | Unique identifier for a user                                                                                                                                                                                                                     |                |
| `"day"`    | `Date`         | Date of the day tracked for engagement                                                                                                                                                                                                           |                |
| `score`    | `Integer`      | Engagement score is an integer reflecting a percentage from 0 to 125 and the value depends on account configuration. For more information, see [Engagement Score](https://help.salesforce.com/s/articleView?id=sf.mc_pers_engagement_score.htm). |                |

### Indexes

- `UNIQUE INDEX user_engagement_history_user_id_key ON user_engagement_history USING btree (user_id, "day")`

[Back to top](#in-this-article)

---

## Table user_goal_completion

Since goal completions often involve a purchase, purchase data is stored at the top level in this table and is empty for non-purchase goal completions

| Field Name                | Data Type                     | Description                                                                       | Example values                                     |
| ------------------------- | ----------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------- |
| `user_id`                 | `Varchar(200)`                | User who satisfied the goal criteria                                              |                                                    |
| `goal_ts`                 | `Timestamp` without time zone | Timestamp of the goal completion in UTC                                           |                                                    |
| `goal_id`                 | `Varchar(256)`                | One of: segment id or purchase (`p`)                                              | `p`                                                |
| `order_id`                | `Varchar(256)`                | Unique identifier for the order. This ID comes from the customer.                 |                                                    |
| `order_currency`          | `Varchar(256)`                | Currency used to purchase                                                         |                                                    |
| `order_line_item_count`   | `Smallint`                    | Count of line items in the order                                                  |                                                    |
| `order_total_value`       | `Numeric(18,4)`               | Sum of quantity \* price for all line items                                       |                                                    |
| `order_units_count`       | `Smallint`                    | Count of units in the order                                                       |                                                    |
| `order_visit_age_minutes` | Double precision              | Age of the visit at the time of the purchase goal completion                      |                                                    |
| `order_visit_time`        | `Timestamp` without time zone | UTC date and time of the visit during which this order was made                   |                                                    |
| `browser`                 | `Varchar(256)`                | Client browser application                                                        | `Safari`, `Chrome`, `Firefox`, `IE`, `other`       |
| `device`                  | `Varchar(256)`                | Client hardware device                                                            | `mobile`, `computer`, `tablet`, `other`            |
| `engagement`              | `Varchar(256)`                | Engagement for the associated user                                                | `low`, `medium`, `high`                            |
| `has_purchased`           | `Boolean`                     | Set when the user makes a purchase                                                |                                                    |
| `is_anonymous`            | `Boolean`                     | `true` when the user isn’t named (identified)                                     |                                                    |
| `is_first_time`           | `Boolean`                     | `true` when the completion represents a first encounter with a visitor            |                                                    |
| `os`                      | `Varchar(256)`                | Operating system - x is "macOS X"                                                 | `x`, `windows`, `linux`, `ios`, `android`, `other` |
| `platform`                | `Varchar(256)`                | Platform used in the goal completion (email, web)                                 | `Email`, `Web`                                     |
| `source`                  | `Varchar(256)`                | For customers who use the mobile SDK, each mobile app would be a separate source. |                                                    |

### Indexes

- `UNIQUE INDEX user_goal_completion_user_id_key ON user_goal_completion USING btree (user_id, goal_id, goal_ts)`

[Back to top](#in-this-article)

---

## Table user_impression

Stores impression events associated with a campaign at the visit level, with the most recent event associated with `event_ts`.

| Field Name         | Data Type                     | Description                                                                       | Example values                                     |
| ------------------ | ----------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------- |
| `user_id`          | `Varchar(200)`                | Unique identifier for the user                                                    |                                                    |
| `experience_id`    | `Varchar(256)`                | Unique identifier for the experience                                              |                                                    |
| `event_ts`         | `Timestamp` without time zone | UTC date and time of the most recent impression in a session.                     |                                                    |
| `user_group`       | `Char(1)`                     | The user group associated with the user and experience - control (C) or test (D)  |                                                    |
| `browser`          | `Varchar(256)`                | Client browser application                                                        | `Safari`, `Chrome`, `Firefox`, `IE`, `other`       |
| `device`           | `Varchar(256)`                | Client hardware device                                                            | `mobile`, `computer`, `tablet`, `other`            |
| `engagement`       | `Varchar(256)`                | Engagement for the associated user                                                | `low`, `medium`, `high`                            |
| `has_purchased`    | `Boolean`                     | Set when the user makes a purchase                                                |                                                    |
| `impression_count` | `Smallint`                    | Total number of impressions for the session                                       |                                                    |
| `is_anonymous`     | `Boolean`                     | `true` when the user isn’t named (identified)                                     |                                                    |
| `is_firsttime`     | `Boolean`                     | `true` when this visit is a user's first                                          |                                                    |
| `os`               | `Varchar(256)`                | Operating system - x is "macOS X"                                                 | `x`, `windows`, `linux`, `ios`, `android`, `other` |
| `platform`         | `Varchar(256)`                | Platform associated with the impressions                                          | `Email`, `Web`                                     |
| `source`           | `Varchar(256)`                | For customers who use the mobile SDK, each mobile app would be a separate source. |                                                    |

### Indexes

- `PRIMARY KEY user_impression_pkey ON user_impression USING btree (user_id, experience_id, event_ts)`

[Back to top](#in-this-article)

---

## Table user_order

Stores purchases. Only purchased orders are kept in the Data Warehouse, nothing open

| Field Name                 | Data Type                     | Description                                                                                                            | Example values |
| -------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------- |
| `id`                       | `Varchar(100)`                | Unique identifier for the order. This ID comes from the customer.                                                      |                |
| `user_id`                  | `Varchar(200)`                | Unique identifier for the user                                                                                         |                |
| `order_num`                | `Smallint`                    | 1-based sequence of orders for this user. Based on the array order in the operational store. (Not set by the customer) |                |
| `visit_start_ts`           | `Timestamp` without time zone | Start time of the visit in which this order was placed                                                                 |                |
| `visit_num`                | `Integer`                     | Visit in which order create time falls within the visit start or end.                                                  |                |
| `created_ts`               | `Timestamp` without time zone | UTC date and time at which the order was created                                                                       |                |
| `updated_ts`               | `Timestamp` without time zone | UTC date and time the order was most recently updated                                                                  |                |
| `purchased_ts`             | `Timestamp` without time zone | UTC date and time the purchase was made                                                                                |                |
| `visit_age_at_purchase_ms` | `Integer`                     | Age of the session, in milliseconds, at purchase time                                                                  |                |
| `num_items`                | `Integer`                     | Number of items in the order                                                                                           |                |
| `num_units`                | `Integer`                     | Number of units (distinct items) in the order                                                                          |                |
| `total_value`              | `Numeric(18,4)`               | Total value of the purchase                                                                                            |                |
| `currency`                 | `Varchar(200)`                | Currency used to make the purchase                                                                                     |                |
| `status`                   | `Varchar(200)`                | Purchased only, other states not stored in the warehouse. (`Open`, `Purchased`, `Canceled`).                           |                |

### Indexes

- `PRIMARY KEY user_order_pkey ON user_order USING btree (id)`
- `UNIQUE INDEX user_order_user_id_key ON user_order USING btree (user_id, created_ts)`

### Referenced by

- `TABLE "order_line_item_attribute" CONSTRAINT "order_line_item_attribute_order_id_fkey" FOREIGN KEY (order_id) REFERENCES user_order(id)`
- `TABLE "order_line_item" CONSTRAINT "order_line_item_order_id_fkey" FOREIGN KEY (order_id) REFERENCES user_order(id)`
- `TABLE "user_order_attribute" CONSTRAINT "user_order_attribute_order_id_fkey" FOREIGN KEY (order_id) REFERENCES user_order(id)`

[Back to top](#in-this-article)

---

## Table user_order_attribute

Name-value pairs associated with an order

| Field Name                        | Data Type      | Description                                                                                                          | Example values                                                   |
| --------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `order_id`                        | `Varchar(100)` | Unique identifier for the order                                                                                      |                                                                  |
| `user_id`                         | `Varchar(200)` | User who made the purchase                                                                                           |                                                                  |
| `order_num`                       | `Smallint`     | Internally generated 1-based sequence indicating the order number                                                    |                                                                  |
| `attribute_name`                  | `Varchar(256)` | The name of the attribute                                                                                            |                                                                  |
| `attribute_value`                 | `Varchar(256)` | The value of the attribute                                                                                           |                                                                  |
| `value_metadata_origin`           | `Varchar(256)` | The name of the entity that issues or creates the initial attribute value                                            | `CRM`, `PointOfSaleSystem`, `FulfillmentSystem`, `LoyaltySystem` |
| `value_metadata_provider`         | `Varchar(256)` | The name of the entity that is providing the attribute                                                               | `CsvUserEtlJob:user-20190528.csv.gz`                             |
| `value_metadata_gear_id`          | `Varchar(256)` | ID of the Personalization gear that updated the attribute, or `null` if it wasn’t updated by a gear                  |                                                                  |
| `value_metadata_last_updated_ts`  | `Varchar(256)` | UTC date and time when the attribute was last updated                                                                |                                                                  |
| `value_metadata_last_verified_ts` | `Varchar(256)` | UTC date and time when the attribute value was last verified as being true and belonging to the specified individual |                                                                  |
| `value_metadata_classification`   | `Varchar(256)` | Metadata relevant or pertaining to the security classification of a given attribute's value                          |                                                                  |

### Indexes

- `PRIMARY KEY user_order_attribute_pkey ON user_order_attribute USING btree (user_id, order_id, attribute_name)`

[Back to top](#in-this-article)

---

## Table user_search

User search terms (some normalization and tokenization is performed)

| Field Name           | Data Type                     | Description                                                | Example values |
| -------------------- | ----------------------------- | ---------------------------------------------------------- | -------------- |
| `user_id`            | `Varchar(200)`                | User who performed the search                              |                |
| `term`               | `Varchar(200)`                | Search term (tokenized)                                    |                |
| `most_recent_search` | `Timestamp` without time zone | UTC date and time of the most recent search for this term  |                |
| `product_clicks`     | `Integer`                     | Count of product clicks associated with the search         |                |
| `purchase_value`     | `Numeric(18,4)`               | Total purchase value of orders associated with this search |                |
| `search_count`       | `Integer`                     | Total number of searches for this term                     |                |

### Indexes

- `PRIMARY KEY user_search_pkey ON user_search USING btree (user_id, term)`

[Back to top](#in-this-article)

---

## Table user_user_visit_lookup

Use this table to join the `user_visit_detail` with other tables containing a `user_id`. The `user_id` in this table corresponds to the general notion of `user_id` in the database, and `user(id)`. The `user_visit_key` is the `user_id` in the `user_visit_detail` table.

| Field Name       | Data Type      | Description                                     | Example values |
| ---------------- | -------------- | ----------------------------------------------- | -------------- |
| `user_id`        | `Varchar(200)` | User id from the user table                     |                |
| `user_id_hashed` | `Varchar(200)` | Hashed user id from the user_visit_detail table |                |

### Indexes

- `UNIQUE INDEX user_user_visit_lookup_user_id_key ON user_user_visit_lookup USING btree (user_id, user_id_hashed)`

[Back to top](#in-this-article)

---

## Table user_visit

Stores information about the user visit

Fields that only appear in user visit: `referring_campaign_id`, `weather`, `previous_path`, `temperature`, `referrer`, `num_pageviews`, `num_events`, `last_event_ts`, `visit_num`

Fields that appear in both user visit and user visit detail: `is_anonymous`, `browser`, `engagement`, `source`, `utm_parameters`, `device`, `is_firsttime`, `has_purchased`, `platform`, `start_ts`, `_dw_created_ts`, `os`, `user_id`

**note:** The `user_id` `user_visit_detail` is a hash value of the user ID in this table; use `user_user_lookup` to join

| Field Name              | Data Type                     | Description                                                                                                                                                    | Example values                                     |
| ----------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `user_id`               | `Varchar(200)`                | User id associated with the visit                                                                                                                              |                                                    |
| `visit_num`             | `Smallint`                    | Internally generated sequence value in the visit history - the visit number.                                                                                   |                                                    |
| `num_events`            | `Integer`                     | Count of events for the visit                                                                                                                                  |                                                    |
| `previous_path`         | `Varchar(100)`                | The most recent page view action for this visit (operation field)                                                                                              |                                                    |
| `num_pageviews`         | `Integer`                     | Count of pages viewed in the visit                                                                                                                             |                                                    |
| `referring_campaign_id` | Varchar(32)                   | External campaign that drove the visit                                                                                                                         |                                                    |
| `device`                | `Varchar(100)`                | Client hardware device                                                                                                                                         | `mobile`, `computer`, `tablet`, `other`            |
| `engagement`            | `Varchar(100)`                | Engagement for the associated user                                                                                                                             | `low`, `medium`, `high`                            |
| `os`                    | `Varchar(100)`                | Operating system - x is "macOS X"                                                                                                                              | `x`, `windows`, `linux`, `ios`, `android`, `other` |
| `browser`               | `Varchar(100)`                | Client browser application                                                                                                                                     | `Safari`, `Chrome`, `Firefox`, `IE`, `other`       |
| `platform`              | `Varchar(100)`                | Platform used in the goal completion (email, web)                                                                                                              | Email, Web                                         |
| `temperature`           | `Varchar(100)`                | Recorded temperature at the physical location of the user during the visit time                                                                                |                                                    |
| `weather`               | `Varchar(100)`                | Recorded weather at the physical location of the user during the visit time                                                                                    |                                                    |
| `referrer`              | `Varchar(2048)`               | HTTP referrer for the visit                                                                                                                                    |                                                    |
| `start_ts`              | `Timestamp` without time zone | UTC date and time the visit began                                                                                                                              |                                                    |
| `last_event_ts`         | `Timestamp` without time zone | UTC date and time of the most recent event in the visit                                                                                                        |                                                    |
| `utm_parameters`        | `Varchar(100)`                | Urchin Tracking Module (UTM) parameters identify the marketing campaign that refers traffic to a specific website and are associated with the visit's referrer |                                                    |
| `has_purchased`         | `Boolean`                     | Set when the user makes a purchase                                                                                                                             |                                                    |
| `is_anonymous`          | `Boolean`                     | `true` when the user isn’t named (identified)                                                                                                                  |                                                    |
| `is_first_time`         | `Boolean`                     | `true` when this visit is the user's first                                                                                                                     |                                                    |
| `source`                | `Varchar(10)`                 | For customers who use the mobile SDK, each mobile app would be a separate source                                                                               |                                                    |

### Indexes

- `PRIMARY KEY user_visit_pkey ON user_visit USING btree (user_id, start_ts)`
- `UNIQUE INDEX user_visit_user_id_key ON user_visit USING btree (user_id, visit_num)`

### Referenced by

- `TABLE "user_order" CONSTRAINT "user_order_user_id_visit_num_fkey" FOREIGN KEY (user_id, visit_num) REFERENCES user_visit(user_id, visit_num)`
- `TABLE "user_order" CONSTRAINT "user_order_user_id_visit_start_ts_fkey" FOREIGN KEY (user_id, visit_start_ts) REFERENCES user_visit(user_id, start_ts)`

[Back to top](#in-this-article)

---

## Table user_visit_detail

Stores additional information about the user visit - location and referrer are usually of interest.

The following fields appear only in the visit detail, not the visit: `region_code`, `referrer_domain`, `revenue`, `city_code`, `metro_code`, `longitude`, `industry_code`, `referring_campaign`, `country_code`, `action_count`, `page_view_count`, `referrer_subdomain`, `referrer_url`, `referrer_terms`, `referrer_source`, `latitude`, `duration_minutes`, `referrer_landing_url`, `referrer_medium`

Fields that appear in both this table and `user_visit`: `is_anonymous`, `browser`, `engagement`, `source`, `utm_parameters`, `device`, `is_firsttime`, `has_purchased`, `platform`, `start_ts`, `_dw_created_ts`, `os`, `user_id`

**note:** The `user_id` in this table is a hash value on the `user_id` in `user_visit`

| Field Name             | Data Type                     | Description                                                                                                                                                    | Example values                                        |
| ---------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `user_id_hashed`       | `Varchar(200)`                | Hash code of the user_id (id from the user table) associated with this visit                                                                                   |                                                       |
| `start_ts`             | `Timestamp` without time zone | UTC date and time the visit started                                                                                                                            |                                                       |
| `referrer_medium`      | `Varchar(100)`                | How the user first arrived                                                                                                                                     | `SEARCH`, `EMAIL`, `SOCIAL`, `DIRECT`                 |
| `referrer_source`      | `Varchar(100)`                | Source of the visit                                                                                                                                            | `Google`, `Bing`, `Yahoo!`, `Facebook`, `Pinterest`   |
| `referrer_terms`       | `Varchar(255)`                | Search terms for associated with the referral                                                                                                                  |                                                       |
| `referrer_domain`      | `Varchar(100)`                | Domain of the visit referrer                                                                                                                                   | `google.com`, `bing.com`, `google.de`, `facebook.com` |
| `referrer_subdomain`   | `Varchar(100)`                | Referrer host with subdomain                                                                                                                                   | `www.google.com.mx`                                   |
| `referrer_url`         | `Varchar(2048)`               | URL associated with the visit referrer                                                                                                                         |                                                       |
| `referrer_landing_url` | `Varchar(2048)`               | URL of the first page the user saw                                                                                                                             |                                                       |
| `utm_parameters`       | `Varchar(100)`                | Urchin Tracking Module (UTM) parameters identify the marketing campaign that refers traffic to a specific website and are associated with the visit's referrer |                                                       |
| `latitude`             | `Numeric(9,6)`                | Latitude associated with the visitor's physical location                                                                                                       |                                                       |
| `longitude`            | `Numeric(9,6)`                | Longitude associated with the visitor's physical location                                                                                                      |                                                       |
| `country_code`         | `Varchar(100)`                | 2-letter Country code associated with the visit                                                                                                                |                                                       |
| `region_code`          | `Varchar(100)`                | Region code associated with the visit                                                                                                                          |                                                       |
| `metro_code`           | `Integer`                     | Metro code associated with the visit. Metro codes for US are Nielsen DMA codes                                                                                 |                                                       |
| `city_code`            | `Integer`                     | Code for the city associated with the visit                                                                                                                    |                                                       |
| `industry_code`        | `Integer`                     | NAICS industry code                                                                                                                                            |                                                       |
| `referring_campaign`   | `Varchar(32)`                 | External campaign that drove the visit                                                                                                                         |                                                       |
| `device`               | `Varchar(100)`                | Client hardware device                                                                                                                                         | `mobile`, `computer`, `tablet`, `other`               |
| `engagement`           | `Varchar(100)`                | Engagement for the associated user                                                                                                                             | `low`, `medium`, `high`                               |
| `os`                   | `Varchar(100)`                | Operating system - x is "macOS X"                                                                                                                              | `x`, `Windows`, `Linux`, `iOS`, `Android`, `other`    |
| `browser`              | `Varchar(100)`                | Client browser application                                                                                                                                     | `Safari`, `Chrome`, `Firefox`, `IE`, `other`          |
| `platform`             | `Varchar(100)`                | Platform (email, web)                                                                                                                                          | `Email`, `Web`, `Mobile`                              |
| `has_purchased`        | `Boolean`                     | Set when the user makes a purchase                                                                                                                             |                                                       |
| `is_anonymous`         | `Boolean`                     | `true` when the user isn’t named (identified)                                                                                                                  |                                                       |
| `is_first_time`        | `Boolean`                     | `true` when this visit is the user's first                                                                                                                     |                                                       |
| `source`               | `Varchar(10)`                 | For customers who use the mobile SDK, each mobile app would be a separate source                                                                               |                                                       |
| `duration_minutes`     | Double precision              | Time spent in the visit, in minutes                                                                                                                            |                                                       |
| `revenue`              | `Numeric(18,4)`               | Total revenue associated with purchases made during the visit                                                                                                  |                                                       |
| `action_count`         | `Integer`                     | Count of actions performed this visit                                                                                                                          |                                                       |
| `page_view_count`      | `Integer`                     | Count of pages viewed this visit                                                                                                                               |                                                       |

### Indexes

- `PRIMARY KEY user_visit_detail_pkey ON user_visit_detail USING btree (user_id_hashed, start_ts)`

[Back to top](#in-this-article)

## See Also

- [_Salesforce Help_: Engagement Score](https://help.salesforce.com/s/articleView?id=sf.mc_pers_engagement_score.htm)
- [_External Link_: IBAN Alpha-2 and Alpha-3 Country Codes](https://www.iban.com/country-codes)

<!-- document id=b06516cc0cdd84f5ca235749f58bbb29b7b54a7f63438ef0bb9c6ad6b9deb35b url=/developer/current/en-us/personalization/personalization/guides/data-modeling.md -->

# Data Modeling

Data modeling in Marketing Cloud Personalization involves the configuration of the platform to represent the key business information for your company. Data in Personalization represents three primary areas of key information: user behaviors, tracked at the user, account, business, or household level; shadow catalog information, representing key business objects; and statistical tracking of key performance indicators, such as purchase revenue.

The configuration of these features is accomplished in the Personalization platform by administrators during initial setup.

- User
  - Identity
  - [Attributes](https://developer.salesforce.com/docs/marketing/personalization/guide/data-modeling/attributes.md)
  - Segments
  - Visits
  - Behaviors
  - Campaign Interactions
  - Orders & Goal Completions
- Accounts / Households
  - Identity
  - [Attributes](https://developer.salesforce.com/docs/marketing/personalization/guide/data-modeling/attributes.md)
  - Segments
  - Aggregate behaviors
- Shadow Catalog
  - Items (For example, Products.)
    - [Attributes](https://developer.salesforce.com/docs/marketing/personalization/guide/data-modeling/attributes.md)
    - Related catalog objects

<!-- document id=3238e42c936a5f037cbcd8b32868d62126b822f6783ac0a2c33bcb37b6e0ab4f url=/developer/current/en-us/personalization/personalization/guides/data-analytics/data-warehouse.md -->

# Data Warehouse

The Marketing Cloud Personalization Data Warehouse enables business analysts to connect BI tools to Personalization, and data scientists to analyze and enhance Personalization data as well as use the power of machine learning.

**note:** The Data Warehouse is available only to customers who have already purchased the Marketing Cloud Personalization - Data Warehouse add-on product.

## In This Article

This article discusses the following topics related to the Personalization Data Warehouse:

- What data is accessible?
- Physical Data Model Entity Relationship Diagram (ERD)
- Data Warehouse Dimensions
- Data Warehouse Activity (Fact) Tables

## What Data Is Accessible?

For every prospect, customer, and account who engages with your organization, Personalization maintains a unified profile that stores engagement details and a contextual understanding of the individual’s behavior. Profiles also include attribute data ingested from external sources or captured with each web visit. This attribute data includes things like referring sources, geolocation, and browser.

Personalization tracks detailed engagement statistics at the product level, as well as transactional data such as registrations, downloads, purchases, adds-to-cart. Using the Data Warehouse, business analysts can access this information to identify trends and patterns related to their product or content catalogs.

**important:** The Personalization Data Warehouse currently doesn’t support data related to User Owned Objects and Article, Blog, and Promotion catalog objects.

## Physical Data Model ERD

The following ERD shows the relationships between the **Dimension** and **Activity** (Fact) tables of the Personalization Data Warehouse. The [Data Dictionary](https://developer.salesforce.com/docs/marketing/personalization/guide/data-dictionary.md) article provides the complete data specifications on these tables in alphabetical order.

**important:** The `_dw_created_ts` field present in all Personalization Data Warehouse tables is a system field for tracking when a record was created. We advise against building dependencies on it as its name or the logic behind it can change without notice.

Instead, we recommend using the `created_ts` or `update_ts` fields, or other fields documented in the [Data Dictionary](https://developer.salesforce.com/docs/marketing/personalization/guide/data-dictionary.md) that are more suited to your use case.

### ERD Details

Due to the size of the full data warehouse model, we've provided **ERD Detail** sections at the end of each dimension and activity table sections for clarity. These sections present just the portion of the data warehouse ERD discussed. These sections show the following information for the tables in the ERD:

- Table name
- Field names
- Field data types (d=date, #=number, t=text/string, b=boolean, c=code)
- Primary Keys (indicated by key icon)
- Foreign Keys (indicated by "up-and-out" arrow)
- Fields used as Foreign Key by other tables (indicated by "down-and-in" arrow)

![ER Diagram](https://developer.salesforce.com/media/data-analytics/data-warehouse-erd.png)

## Data Warehouse Dimensions

The dimension tables in the default Personalization Data Warehouse provide the context for data analysis in the following dimensions:

- User
- Product
- Campaign
- Location (deprecated)
- User Segment
- Customer Survey (deprecated)

### Tables by Dimension

The following sections present the data warehouse tables used to store data for each dimension.

#### User

The dimension tables that store data associated with the User dimension include the following:

- `user`
- `user_attribute`
- `user_alias`

#### Product

The dimension tables that store data associated with the Product dimension include the following:

- `product`
- `product_category`
- `category`
- `product_attribute`
- `product_dimension`
- `dimension`

#### Campaign

The dimension tables that store data associated with the Campaign dimension include the following:

- `campaign`
- `experience`

#### Location (deprecated)

The dimension tables that store data associated with the Location (affiliate) dimension include the following:

- `location` (deprecated)
- `country` (deprecated)

**important:** The `location` and `country` dimension tables are now deprecated and no longer in use.

#### User Segment

The `segment` dimension table stores data associated with the specific segment for which a user has qualified.

#### Customer Survey (deprecated)

The `survey_question` dimension table stores data associated with the customer survey questions that exist in the current system.

**important:** The `survey_question` dimension table is now deprecated and no longer in use.

### ERD Detail - Dimensions

The following sections present the tables in the **Dimension** side of the data warehouse ERD broken into top and bottom sections.

#### ERD Detail - Dimension Top

![Dimension Top](https://developer.salesforce.com/media/data-analytics/data-warehouse-erd-dimension-top.png)

#### ERD Detail - Dimension Bottom

![Dimension Bottom](https://developer.salesforce.com/media/data-analytics/data-warehouse-erd-dimension-bottom.png)

## Data Warehouse Activity (Fact) Tables

The following sections list the activity (fact) tables in the default Personalization data warehouse that collect and store the values used with dimension tables analysis. The tables are presented in the order in which they appear in the **Activity** side of the ERD shown in this article (left-to-right, top-to-bottom). The **ERD Detail** section at the end of each subsection presents corresponding table details for the listed tables.

### Activity Tables - ERD Top

The activity tables in the top portion of the ERD Activity side include:

- `user_visit_detail`
- `user_visit_detail_utm_parameters`
- `path` (affiliate)
- `user_search`
- `user_send`
- `user_send_activity`

#### ERD Detail - Activity Top

![Activity Top](https://developer.salesforce.com/media/data-analytics/data-warehouse-erd-activity-top.png)

### Activity Tables - ERD Middle-Left

The activity tables in the middle-left portion of the ERD Activity side include:

- `segment_membership`
- `user_campaign_state`
- `user_click`
- `user_order_attribute`
- `order_line_item_attribute`
- `user_order`
- `user_user_visit_lookup`
- `user_impression`

#### ERD Detail - Activity Middle-Left

![Activity Middle-Left](https://developer.salesforce.com/media/data-analytics/data-warehouse-erd-activity-middle-left.png)

### Activity Tables - ERD Middle-Right

The activity tables in the middle-right portion of the ERD Activity side include:

- `user_daily_stat_item_stat_promotion`
- `user_goal_completion`

#### ERD Detail - Activity Middle-Right

![Activity Middle-Right](https://developer.salesforce.com/media/data-analytics/data-warehouse-erd-activity-middle-right.png)

### Activity Tables - ERD Bottom-Left

The activity tables in the bottom-left portion of the ERD Activity side include:

- `order_line_item`
- `goal_completion_attribution`
- `user_visit`
- `user_daily_stat_item_stat_category`
- `user_daily_stat_item_stat_product`
- `goal_completion_line_item`
- `user_dismissal`
- `goal_completion_attribution_promoted_item`
- `survey_response` (depracated)

**important:** The `survey_response` dimension table is now deprecated and no longer in use.

#### ERD Detail - Activity Bottom-Left

![Activity Bottom-Left](https://developer.salesforce.com/media/data-analytics/data-warehouse-erd-activity-bottom-left.png)

### Activity Tables - ERD Bottom-Right

The activity tables in the bottom-right portion of the ERD Activity side include:

- `user_daily_stat_item_stat_product`
- `user_daily_stat`
- `user_daily_stat_action`
- `user_engagement_history`
- `user_daily_stat_item_stat_dimension`

#### ERD Detail - Activity Bottom-Right

![Activity Bottom-Left](https://developer.salesforce.com/media/data-analytics/data-warehouse-erd-activity-bottom-right.png)

<!-- document id=1917fe57dfc429a506577459b9971a476e648274a63a4fc10e74c23e39dad64d url=/developer/current/en-us/personalization/personalization/guides/data-modeling/datasets.md -->

# Datasets

Datasets represent an instance of Marketing Cloud Personalization for use in personalization. User profiles, campaign configurations, and other features of Personalization are all scoped to a dataset. This scoping strategy enables you to use different datasets on different sites, geographies, or deployment environments. For example, while splitting datasets between your QA and production environments is common, it is also helpful to maintain separate datasets for your French and German sites.

Datasets are placed within Identity Groups to coordinate user identities between environments, ensuring that you're not emailing the same user from the French and German environments while still letting each dataset coordinate that user's personalization.

<!-- document id=420dda6192f61a157fbba702918f90f9f573d457548ae2dbaf36f20a5ec5c110 url=/developer/current/en-us/personalization/personalization/guides/custom-interface-template-configuration/properties/datetime.md -->

# DateTime Property

## Date Picker

A date picker input.

```typescript
dateProperty: DateTime;
```

![Date Picker](https://developer.salesforce.com/media/interface-template-configuration/DateTime.png)

The value returned from the selection is structured as an object with a single `dateTime` property. The property is an array of strings representing the date and time in ISO 8601 format (for example, 2019-10-08T16:00:00.000Z).

The object structure is as follows:

```typescript
{
    dateTime: string[]
}
```

**note:** Even if the `DateTime` picker only intends to return a single date, it still returns an array.

---

## Date Range

The picker can be configured to return a range using the `@range` decorator.

```typescript
@range(true)
dateProperty: DateTime;
```

In this case, the returned array value has the start of the range in the 0 index of the array, and the end of the range in the 1 index.

<!-- document id=e9ba3d341395a63dc35b69525ee9b2ad5c31dff7871abaa20fee2f4b2221debb url=/developer/current/en-us/personalization/personalization/guides/custom-interface-template-configuration/decorators.md -->

# Decorators

## Title

The label for the input, to be used instead of the default title case conversion of the property name.

```typescript
@title("A Custom Title")
simpleProperty : string;
```

![Title](https://developer.salesforce.com/media/interface-template-configuration/Title.png)

---

## Subtitle

A subtitle for the input.

```typescript
@subtitle("Some information about what to put here")
simpleProperty : string;
```

![Subtitle](https://developer.salesforce.com/media/interface-template-configuration/Subtitle.png)

---

## Units

For information on the `@units` decorator, see [Number Property](https://developer.salesforce.com/docs/marketing/personalization/guide/properties/number.md).

---

## Header

Adds a header before the decorated property, indicating all properties below this decorator (until the next header) are intended to be a section on configurables.

```typescript
simpleProperty : string;

@header('Section Header')

simpleProperty2: string;

simpleProperty3: string;
```

![Header](https://developer.salesforce.com/media/interface-template-configuration/Header.png)

In the preceding example, `simpleProperty2` and `simpleProperty3` fall under the header "Section Header".

---

## Header Subtitle

Additional text to describe a section, can be used to provide the end user with instructions.

```typescript
simpleProperty : string;

@header('Section Header')
@headerSubtitle('A brief explanation of this section.')

simpleProperty2: string;

simpleProperty3: string;
```

![HeaderSubtitle](https://developer.salesforce.com/media/interface-template-configuration/HeaderSubtitle.png)

## Markdown

Basic Markdown rendered before the decorated property. Syntaxes are limited to the following examples.

```typescript
@markdown(`
# H1
## H2
### H3
#### H4
##### H5
###### H6

**bold text**
*italicized text*

Ordered Lists

1. Ordered List Item 1
2. Ordered List Item 2
3. Ordered List Item 3


Unordered Lists

- Unordered List Item 1
- Unordered List Item 2


Horizontal Rule

---

[Link](https://www.salesforce.com/)
`)
simpleProperty : string;
```

![Markdown](https://developer.salesforce.com/media/interface-template-configuration/Markdown.png)

---

## Optional

The `@optional` decorator enables you to flag properties as either optional or required.

```typescript
@optional(true)
simpleProperty : string;
```

**note:** Personalization doesn’t prevent you from saving a campaign with empty or incomplete template properties that are flagged as required. For example, even if a `simpleText: string` property is tagged as required by using the `@optional(false)` decorator, a campaign developer can still save a campaign with the `simpleText` property field left empty or incomplete.

---

## Hidden

Hides the input from the user.

```typescript
@hidden(true)
simpleProperty : string;
```

This decorator can also accept a function in order to hide configurables conditionally. The arguments for the decorator are `this`, and a function whose first argument is `self`, the instance of this class.

The function MUST return a boolean `true` or `false`. Returning a non-boolean `truthy` or `falsy` value (for example, 0, 1, 'some string') throws an error.

```typescript
simpleBoolean : boolean;

@hidden(this, (self) => self.simpleBoolean)
conditionalField: string;
```

---

## Shown If

The inverse of the `@hidden` decorator, displays the field if true, hides the field if false.

```typescript
@shownIf(true)
simpleProperty : string;
```

```typescript
simpleBoolean : boolean;

@shownIf(this, (self) => self.simpleBoolean)
conditionalField: string;
```

---

## Rich Text

For information on the `@richText` decorator, see [String Property](https://developer.salesforce.com/docs/marketing/personalization/guide/properties/string.md).

---

## Options

For information on the `@options` decorator, see [Select Property](https://developer.salesforce.com/docs/marketing/personalization/guide/properties/select.md).

---

## Button Group

Renders a static list of options as a button group.

```typescript
@buttonGroup(true)
simpleOption : "option1" | "option2" | "option3";
```

---

## Range

For information on the `@range` decorator, see [DateTime Property](https://developer.salesforce.com/docs/marketing/personalization/guide/properties/datetime.md).

---

## Tabular

Displays the fields of a complex object horizontally.

```typescript
@tabular()
complexObject : SomeComplexType;
```

Arrays of complex objects are rendered like a table. Include `headersPerRow: true` to show field titles on each row. Optionally render a line to visually divide each row by including `dividerLine: true`.

```typescript
@tabular({dividerLine: true, headersPerRow:false})
complexObjectList : SomeComplexType[];
```

<!-- document id=75cc40de817313a9dbc267344ad47eab48dd189a13bd695d27f4235c49a79ce2 url=/developer/current/en-us/personalization/personalization/guides/web-integration/example-sitemaps/ecommerce.md -->

# ecommerce

The following code sample depicts sitemap code for an imaginary implementation of Marketing Cloud Personalization on the Northern Trail Outfitters website `https://www.northerntrailoutfitters.com`. This sitemap code is not exhaustive and maps only key areas valuable for demonstrating an example implementation of Personalization. The primary focus of this sitemap code is to depict how to approach designing a Catalog for ecommerce websites.

**important:** This example sitemap is for reference purposes only. Avoid copying this code into your Sitemap Editor as it does not produce the results you intended. 

This example includes an SKU implementation, however most sitemaps don't require them. For more information about Marketing Cloud Personalization SKU implementation, see [Stock Keeping Units](https://help.salesforce.com/s/articleView?id=mktg.mc_pers_catalog_object_built_in.htm&type=5#:~:text=currency%2C%20and%20rating.-,Stock%20Keeping%20Units,-Stock%20Keeping%20Units).

## Example Sitemap in the SalesforceInteractions Namespace

```javascript
SalesforceInteractions.init({
  cookieDomain: "northerntrailoutfitters.com",
  consents: [
    {
      purpose: SalesforceInteractions.mcis.ConsentPurpose.Personalization,
      provider: "Example Consent Manager",
      status: SalesforceInteractions.ConsentStatus.OptIn,
    },
  ],
}).then(() => {
  const sitemapConfig = {
    global: {
      onActionEvent: (actionEvent) => {
        const email = SalesforceInteractions.mcis.getValueFromNestedObject(
          "window._etmc.user_info.email",
        );
        if (email) {
          actionEvent.user = actionEvent.user || {};
          actionEvent.user.identities = actionEvent.user.identities || {};
          actionEvent.user.identities.emailAddress = email;
        }
        return actionEvent;
      },
      contentZones: [
        { name: "global_infobar_top_of_page", selector: "header.site-header" },
        { name: "global_infobar_bottom_of_page", selector: "footer.site-footer" },
      ],
      listeners: [
        SalesforceInteractions.listener("submit", ".email-signup", () => {
          const email = SalesforceInteractions.cashDom("#dwfrm_mcsubscribe_email").val();
          if (email) {
            SalesforceInteractions.sendEvent({
              interaction: { name: "Email Sign Up - Footer" },
              user: { identities: { emailAddress: email } },
            });
          }
        }),
      ],
    },
    pageTypeDefault: {
      name: "default",
      interaction: {
        name: "Default Page",
      },
    },
    pageTypes: [
      {
        name: "product_detail",
        /*
                The best practice for isMatch is to match as quickly as possible. If matching immediately is not an option, you can use a Promise.
                The Promise should resolve true or false and not pend indefinitely. This Promise example uses a setTimeout to prevent the isMatch from pending indefinitely if the match condition is not met fast enough. In this scenario, we know that the match condition will be met within 50 milliseconds or not at all. Note that using a timeout like this might not be sufficient in all cases and if you are using a Promise it should be tailored to your specific use-case.
                */
        isMatch: () =>
          new Promise((resolve, reject) => {
            let isMatchPDP = setTimeout(() => {
              resolve(false);
            }, 50);
            return SalesforceInteractions.DisplayUtils.pageElementLoaded(
              "div.page[data-action='Product-Show']",
              "html",
            ).then(() => {
              clearTimeout(isMatchPDP);
              resolve(true);
            });
          }),
        interaction: {
          name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
          catalogObject: {
            type: "Product",
            id: () => {
              return SalesforceInteractions.util.resolveWhenTrue.bind(() => {
                const productId = SalesforceInteractions.cashDom(".product-id").first().text();
                const products = getProductsFromDataLayer();
                if (products && products.length > 0) {
                  return products[0].id;
                } else if (productId) {
                  return productId;
                } else {
                  return false;
                }
              });
            },
            attributes: {
              sku: {
                id: SalesforceInteractions.cashDom(".product-detail[data-pid]").attr("data-pid"),
              },
              name: SalesforceInteractions.resolvers.fromJsonLd("name"),
              description: SalesforceInteractions.resolvers.fromSelector(
                ".short-description",
                (desc) => desc.trim(),
              ),
              url: SalesforceInteractions.resolvers.fromHref(),
              imageUrl: SalesforceInteractions.resolvers.fromSelectorAttribute(
                ".product-carousel .carousel-item[data-slick-index='0'] img",
                "src",
                (url) => window.location.origin + url,
              ),
              inventoryCount: 1,
              price: SalesforceInteractions.resolvers.fromSelector(
                ".prices .price .value",
                (price) => parseFloat(price.replace(/[^0-9\.]+/g, "")),
              ),
              rating: () => {
                return SalesforceInteractions.mcis.extractFirstGroup(
                  /([.\w]+) out of/,
                  SalesforceInteractions.cashDom(".ratings .sr-only").text(),
                );
              },
            },
            relatedCatalogObjects: {
              Category: SalesforceInteractions.DisplayUtils.pageElementLoaded(
                ".container .product-breadcrumb .breadcrumb a",
                "html",
              ).then((ele) => {
                return SalesforceInteractions.resolvers.buildCategoryId(
                  ".container .product-breadcrumb .breadcrumb a",
                  null,
                  null,
                  (categoryId) => [categoryId.toUpperCase()],
                );
              }),
              Gender: SalesforceInteractions.DisplayUtils.pageElementLoaded(
                ".product-breadcrumb .breadcrumb a, h1.product-name",
                "html",
              ).then((ele) => {
                if (
                  SalesforceInteractions.cashDom(".product-breadcrumb .breadcrumb a")
                    .first()
                    .text()
                    .toLowerCase() === "women" ||
                  SalesforceInteractions.cashDom("h1.product-name").text().indexOf("Women") >= 0
                ) {
                  return ["WOMEN"];
                } else if (
                  SalesforceInteractions.cashDom(".product-breadcrumb .breadcrumb a")
                    .first()
                    .text()
                    .toLowerCase() === "men" ||
                  SalesforceInteractions.cashDom("h1.product-name").text().indexOf("Men") >= 0
                ) {
                  return ["MEN"];
                } else {
                  return;
                }
              }),
              Color: SalesforceInteractions.DisplayUtils.pageElementLoaded(
                ".attributes",
                "html",
              ).then((ele) => {
                return SalesforceInteractions.resolvers.fromSelectorAttributeMultiple(
                  ".color-value",
                  "data-attr-value",
                );
              }),
              Feature: SalesforceInteractions.DisplayUtils.pageElementLoaded(
                ".features",
                "html",
              ).then((ele) => {
                return SalesforceInteractions.resolvers.fromSelectorMultiple(
                  ".long-description li",
                  (features) => {
                    return features.map((feature) => {
                      return feature.trim().toUpperCase();
                    });
                  },
                );
              }),
            },
          },
        },
        contentZones: [
          {
            name: "product_detail_recs_row_1",
            selector: ".row.recommendations div[id*='cq']:nth-of-type(1)",
          },
          {
            name: "product_detail_recs_row_2",
            selector: ".row.recommendations div[id*='cq']:nth-of-type(2)",
          },
          { name: "testHeader", selector: ".site-header" },
        ],
        listeners: [
          SalesforceInteractions.listener("click", ".add-to-cart", () => {
            let lineItem = SalesforceInteractions.mcis.buildLineItemFromPageState(
              "select.quantity-select option:checked",
            );
            SalesforceInteractions.sendEvent({
              interaction: {
                name: SalesforceInteractions.CartInteractionName.AddToCart,
                lineItem: lineItem,
              },
            });
          }),
          SalesforceInteractions.listener("click", ".attribute", (event) => {
            let classList = event.target.classList.value.split(" ");
            if (classList.includes("color-value") || classList.includes("size-value")) {
              SalesforceInteractions.sendEvent({
                interaction: {
                  name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObjectDetail,
                  catalogObject: {
                    type: "Product",
                    id: SalesforceInteractions.getSitemapResult().currentPage.interaction
                      .catalogObject.id,
                    attributes: {
                      sku: {
                        id: SalesforceInteractions.cashDom(".product-detail[data-pid]").attr(
                          "data-pid",
                        ),
                      },
                    },
                    relatedCatalogObjects: {
                      Color: [
                        SalesforceInteractions.cashDom(".color-value.selected").attr(
                          "data-attr-value",
                        ),
                      ],
                    },
                  },
                },
              });
            }
          }),
        ],
      },
      {
        name: "Category",
        isMatch: () =>
          new Promise((resolve, reject) => {
            let isMatchCat = setTimeout(() => {
              resolve(false);
            }, 50);
            return SalesforceInteractions.DisplayUtils.pageElementLoaded(
              "#product-search-results",
              "html",
            ).then(() => {
              clearTimeout(isMatchCat);
              resolve(SalesforceInteractions.cashDom(".breadcrumb").length > 0);
            });
          }),
        interaction: {
          name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
          catalogObject: {
            type: "Category",
            id: SalesforceInteractions.DisplayUtils.pageElementLoaded(
              ".breadcrumb .breadcrumb-item a",
              "html",
            ).then((ele) => {
              return SalesforceInteractions.resolvers.buildCategoryId(
                ".breadcrumb .breadcrumb-item a",
                1,
                null,
                (categoryId) => categoryId.toUpperCase(),
              );
            }),
          },
        },
        listeners: [
          SalesforceInteractions.listener("click", ".quickview", (e) => {
            const pid = SalesforceInteractions.cashDom(e.target).attr("href").split("pid=")[1];
            if (!pid) {
              return;
            }

            SalesforceInteractions.sendEvent({
              interaction: {
                name: SalesforceInteractions.CatalogObjectInteractionName.QuickViewCatalogObject,
                catalogObject: {
                  type: "Product",
                  id: pid,
                },
              },
            });
          }),
          SalesforceInteractions.listener("click", "body", (e) => {
            if (
              SalesforceInteractions.cashDom(e.target).closest("button[data-dismiss='modal']")
                .length > 0
            ) {
              SalesforceInteractions.sendEvent({
                interaction: {
                  name: SalesforceInteractions.mcis.CatalogObjectInteractionName
                    .StopQuickViewCatalogObject,
                },
              });
            } else if (
              SalesforceInteractions.cashDom(e.target).closest("#quickViewModal").length > 0 &&
              SalesforceInteractions.cashDom(e.target).find("#quickViewModal .modal-dialog")
                .length > 0
            ) {
              SalesforceInteractions.sendEvent({
                interaction: {
                  name: SalesforceInteractions.mcis.CatalogObjectInteractionName
                    .StopQuickViewCatalogObject,
                },
              });
            }
          }),
        ],
      },
      {
        name: "department",
        isMatch: () =>
          new Promise((resolve, reject) => {
            let isMatchDept = setTimeout(() => {
              resolve(false);
            }, 50);
            return SalesforceInteractions.DisplayUtils.pageElementLoaded(
              "div.category-tile",
              "html",
            ).then(() => {
              clearTimeout(isMatchDept);
              resolve(!/\/homepage/.test(window.location.href));
            });
          }),
      },
      {
        name: "search_results",
        isMatch: () => /\/default\/search$/.test(window.location.pathname),
      },
      {
        name: "cart",
        isMatch: () => /\/cart/.test(window.location.href),
        interaction: {
          name: SalesforceInteractions.CartInteractionName.ReplaceCart,
          lineItems: SalesforceInteractions.DisplayUtils.pageElementLoaded(
            ".cart-empty, .checkout-btn",
            "html",
          ).then(() => {
            let cartLineItems = [];
            SalesforceInteractions.cashDom(".product-info .product-details").each((index, ele) => {
              let itemQuantity = parseInt(
                SalesforceInteractions.cashDom(ele).find(".qty-card-quantity-count").text().trim(),
              );
              if (itemQuantity && itemQuantity > 0) {
                let lineItem = {
                  catalogObjectType: "Product",
                  catalogObjectId: SalesforceInteractions.cashDom(ele)
                    .find(".line-item-quanity-info")
                    .attr("data-pid"),
                  price:
                    SalesforceInteractions.cashDom(ele)
                      .find(".pricing")
                      .text()
                      .replace(/[^0-9\.]+/g, "") / itemQuantity,
                  quantity: itemQuantity,
                };
                cartLineItems.push(lineItem);
              }
            });
            return cartLineItems;
          }),
        },
      },
      {
        name: "order_confirmation",
        isMatch: () => /\/confirmation/.test(window.location.href),
        interaction: {
          name: SalesforceInteractions.OrderInteractionName.Purchase,
          order: {
            id: SalesforceInteractions.DisplayUtils.pageElementLoaded(".order-number", "html").then(
              (ele) => {
                return SalesforceInteractions.resolvers.fromSelector(".order-number");
              },
            ),
            lineItems: SalesforceInteractions.DisplayUtils.pageElementLoaded(
              ".product-line-item",
              "html",
            ).then(() => {
              let purchaseLineItems = [];
              SalesforceInteractions.cashDom(".product-line-item").each((index, ele) => {
                let itemQuantity = parseInt(
                  SalesforceInteractions.cashDom(ele)
                    .find(".qty-card-quantity-count")
                    .text()
                    .trim(),
                );
                if (itemQuantity && itemQuantity > 0) {
                  let lineItem = {
                    catalogObjectType: "Product",
                    catalogObjectId: SalesforceInteractions.cashDom(ele)
                      .find(".line-item-quanity-info")
                      .attr("data-pid")
                      .trim(),
                    price:
                      SalesforceInteractions.cashDom(ele)
                        .find(".pricing")
                        .text()
                        .trim()
                        .replace(/[^0-9\.]+/g, "") / itemQuantity,
                    quantity: itemQuantity,
                  };
                  purchaseLineItems.push(lineItem);
                }
              });
              return purchaseLineItems;
            }),
          },
        },
      },
      {
        name: "login",
        isMatch: () =>
          /\/login/.test(window.location.href) &&
          window.location.hostname !== "community.northerntrailoutfitters.com",
        interaction: {
          name: "Login",
        },
        listeners: [
          SalesforceInteractions.listener("click", "form[name='login-form'] button", () => {
            const email = SalesforceInteractions.cashDom("#login-form-email").val();
            if (email) {
              SalesforceInteractions.sendEvent({
                interaction: { name: "Logged In" },
                user: { identities: { emailAddress: email } },
              });
            }
          }),
        ],
      },
      {
        name: "home",
        isMatch: () => /\/homepage/.test(window.location.href),
        interaction: {
          name: "Homepage",
        },
        contentZones: [
          { name: "home_hero", selector: ".experience-carousel-bannerCarousel" },
          {
            name: "home_sub_hero",
            selector: ".experience-carousel-bannerCarousel + .experience-component",
          },
          { name: "home_popup" },
        ],
      },
      {
        name: "community_login",
        isMatch: () =>
          window.location.hostname === "community.northerntrailoutfitters.com" &&
          /\/s\/login/.test(window.location.href),
        interaction: {
          name: "Community Login",
        },
        listeners: [
          SalesforceInteractions.listener("click", ".loginButton", (event) => {
            const email = SalesforceInteractions.cashDom("input[placeholder='Email']").val();
            if (email) {
              SalesforceInteractions.sendEvent({
                interaction: { name: "Community Log In" },
                user: { identities: { emailAddress: email } },
              });
            }
          }),
        ],
      },
      {
        name: "community_home",
        isMatch: () => {
          return (
            window.location.hostname === "community.northerntrailoutfitters.com" &&
            /^\/s\/?$/.test(window.location.pathname)
          );
        },
        interaction: {
          name: "Community Homepage",
        },
        listeners: [
          SalesforceInteractions.listener("click", "li.topicItem", (event) => {
            const topicLabel = SalesforceInteractions.cashDom(event.currentTarget)
              .find(".topicLabel")
              .text()
              .trim();
            if (topicLabel) {
              SalesforceInteractions.sendEvent({
                interaction: { name: "Community Homepage - " + topicLabel },
              });
            }
          }),
        ],
      },
    ],
  };
  const getProductsFromDataLayer = () => {
    if (window.dataLayer) {
      for (let i = 0; i < window.dataLayer.length; i++) {
        if (
          ((window.dataLayer[i].ecommerce && window.dataLayer[i].ecommerce.detail) || {}).products
        ) {
          return window.dataLayer[i].ecommerce.detail.products;
        }
      }
    }
  };
  SalesforceInteractions.initSitemap(sitemapConfig);
});
```

## Example Sitemap in the Evergage Namespace

```javascript
Evergage.init({
  cookieDomain: "northerntrailoutfitters.com",
}).then(() => {
  const config = {
    global: {
      onActionEvent: (actionEvent) => {
        const email = Evergage.util.getValueFromNestedObject("window._etmc.user_info.email");
        if (email) {
          actionEvent.user = actionEvent.user || {};
          actionEvent.user.attributes = actionEvent.user.attributes || {};
          actionEvent.user.attributes.emailAddress = email;
        }
        return actionEvent;
      },
      contentZones: [
        { name: "global_infobar_top_of_page", selector: "header.site-header" },
        { name: "global_infobar_bottom_of_page", selector: "footer.site-footer" },
      ],
      listeners: [
        Evergage.listener("submit", ".email-signup", () => {
          const email = Evergage.cashDom("#dwfrm_mcsubscribe_email").val();
          if (email) {
            Evergage.sendEvent({
              action: "Email Sign Up - Footer",
              user: { attributes: { emailAddress: email } },
            });
          }
        }),
      ],
    },
    pageTypeDefault: {
      name: "default",
    },
    pageTypes: [
      {
        name: "product_detail",
        isMatch: () => {
          return Evergage.DisplayUtils.pageElementLoaded("div.page", "html").then((ele) => {
            const pageType = Evergage.cashDom(ele).attr("data-action");
            return pageType === "Product-Show";
          });
        },
        catalog: {
          Product: {
            _id: () => {
              return Evergage.util.resolveWhenTrue.bind(() => {
                const productId = Evergage.cashDom(".product-id").first().text();
                const products = getProductsFromDataLayer();
                if (products && products.length > 0) {
                  return products[0].id;
                } else if (productId) {
                  return productId;
                } else {
                  return false;
                }
              });
            },
            sku: { _id: Evergage.cashDom(".product-detail[data-pid]").attr("data-pid") },
            name: Evergage.resolvers.fromJsonLd("name"),
            description: Evergage.resolvers.fromSelector(".short-description"),
            url: Evergage.resolvers.fromHref(),
            imageUrl: Evergage.resolvers.fromSelectorAttribute(
              ".product-carousel .carousel-item[data-slick-index='0'] img",
              "src",
            ),
            inventoryCount: 1,
            price: Evergage.resolvers.fromSelector(".prices .price .value"),
            rating: () => {
              return Evergage.util.extractFirstGroup(
                /([.\w]+) out of/,
                Evergage.cashDom(".ratings .sr-only").text(),
              );
            },
            categories: () => {
              return Evergage.DisplayUtils.pageElementLoaded(
                ".container .product-breadcrumb .breadcrumb a",
                "html",
              ).then((ele) => {
                return Evergage.resolvers.buildCategoryId(
                  ".container .product-breadcrumb .breadcrumb a",
                  null,
                  null,
                  (categoryId) => [categoryId.toUpperCase()],
                );
              });
            },
            relatedCatalogObjects: {
              // In case you're using 'dimensions' instead of 'relatedCatalogObjects', you can continue to do so as they both function the same way.
              Gender: () => {
                return Evergage.DisplayUtils.pageElementLoaded(
                  ".product-breadcrumb .breadcrumb a, h1.product-name",
                  "html",
                ).then((ele) => {
                  if (
                    Evergage.cashDom(".product-breadcrumb .breadcrumb a")
                      .first()
                      .text()
                      .toLowerCase() === "women" ||
                    Evergage.cashDom("h1.product-name").text().indexOf("Women") >= 0
                  ) {
                    return ["WOMEN"];
                  } else if (
                    Evergage.cashDom(".product-breadcrumb .breadcrumb a")
                      .first()
                      .text()
                      .toLowerCase() === "men" ||
                    Evergage.cashDom("h1.product-name").text().indexOf("Men") >= 0
                  ) {
                    return ["MEN"];
                  } else {
                    return;
                  }
                });
              },
              Color: () => {
                return Evergage.DisplayUtils.pageElementLoaded(".attributes", "html").then(
                  (ele) => {
                    return Evergage.resolvers.fromSelectorAttributeMultiple(
                      ".color-value",
                      "data-attr-value",
                    );
                  },
                );
              },
              Feature: () => {
                return Evergage.DisplayUtils.pageElementLoaded(".features", "html").then((ele) => {
                  return Evergage.resolvers.fromSelectorMultiple(
                    ".features .feature",
                    (features) => {
                      return features.map((feature) => {
                        return feature.trim();
                      });
                    },
                  );
                });
              },
            },
          },
        },
        contentZones: [
          {
            name: "product_detail_recs_row_1",
            selector: ".row.recommendations div[id*='cq']:nth-of-type(1)",
          },
          {
            name: "product_detail_recs_row_2",
            selector: ".row.recommendations div[id*='cq']:nth-of-type(2)",
          },
          { name: "testHeader", selector: ".site-header" },
        ],
        listeners: [
          Evergage.listener("click", ".add-to-cart", () => {
            const lineItem = Evergage.util.buildLineItemFromPageState("select[id*=quantity]");
            lineItem.sku = { _id: Evergage.cashDom(".product-detail[data-pid]").attr("data-pid") };
            Evergage.sendEvent({
              itemAction: Evergage.ItemAction.AddToCart,
              cart: {
                singleLine: {
                  Product: lineItem,
                },
              },
            });
          }),
          Evergage.listener("click", ".attribute", (event) => {
            let classList = event.target.classList.value.split(" ");
            if (classList.includes("color-value") || classList.includes("size-value")) {
              Evergage.sendEvent({
                itemAction: Evergage.ItemAction.ViewItemDetail,
                catalog: {
                  Product: {
                    _id: Evergage.util.buildLineItemFromPageState("select[id*=quantity]")._id,
                    sku: { _id: Evergage.cashDom(".product-detail[data-pid]").attr("data-pid") },
                    relatedCatalogObjects: {
                      Color: [Evergage.cashDom(".color-value.selected").attr("data-attr-value")],
                    },
                  },
                },
              });
            }
          }),
        ],
      },
      {
        name: "Category",
        action: "Viewed Category",
        isMatch: () => {
          return Evergage.DisplayUtils.pageElementLoaded(".page", "html").then((ele) => {
            const pageType = Evergage.cashDom(ele).attr("data-action");
            return pageType === "Search-Show" && Evergage.cashDom(".breadcrumb").length > 0;
          });
        },
        catalog: {
          Category: {
            _id: () => {
              return Evergage.DisplayUtils.pageElementLoaded(
                ".breadcrumb .breadcrumb-item a",
                "html",
              ).then((ele) => {
                return Evergage.resolvers.buildCategoryId(
                  ".breadcrumb .breadcrumb-item a",
                  1,
                  null,
                  (categoryId) => categoryId.toUpperCase(),
                );
              });
            },
          },
        },
        listeners: [
          Evergage.listener("click", ".quickview", (e) => {
            const pid = Evergage.cashDom(e.target).attr("href").split("pid=")[1];
            if (!pid) {
              return;
            }

            Evergage.sendEvent({
              action: "Category Page Quick View",
              itemAction: Evergage.ItemAction.QuickViewItem,
              catalog: {
                Product: {
                  _id: pid,
                },
              },
            });
          }),
          Evergage.listener("click", "body", (e) => {
            if (Evergage.cashDom(e.target).closest("button[data-dismiss='modal']").length > 0) {
              Evergage.sendEvent({
                action: "Close Quick View",
                itemAction: Evergage.ItemAction.StopQuickViewItem,
              });
            } else if (
              Evergage.cashDom(e.target).closest("#quickViewModal").length > 0 &&
              Evergage.cashDom(e.target).find("#quickViewModal .modal-dialog").length > 0
            ) {
              Evergage.sendEvent({
                action: "Close Quick View",
                itemAction: Evergage.ItemAction.StopQuickViewItem,
              });
            }
          }),
        ],
      },
      {
        name: "department",
        isMatch: () => {
          return Evergage.DisplayUtils.pageElementLoaded("div.category-tile", "html").then(
            (ele) => {
              return !/\/homepage/.test(window.location.href);
            },
          );
        },
      },
      {
        name: "search_results",
        isMatch: () => /\/default\/search$/.test(window.location.pathname),
      },
      {
        name: "cart",
        isMatch: () => /\/cart/.test(window.location.href),
        itemAction: Evergage.ItemAction.ViewCart,
        catalog: {
          Product: {
            lineItems: {
              _id: () => {
                return Evergage.DisplayUtils.pageElementLoaded(
                  ".cart-empty, .checkout-btn",
                  "html",
                ).then((ele) => {
                  return Evergage.resolvers.fromSelectorAttributeMultiple(
                    ".product-info .product-details .line-item-quantity-info",
                    "data-pid",
                  );
                });
              },
              price: () => {
                return Evergage.DisplayUtils.pageElementLoaded(
                  ".cart-empty, .checkout-btn",
                  "html",
                ).then((ele) => {
                  return Evergage.resolvers.fromSelectorMultiple(
                    ".product-info .product-details .pricing",
                  );
                });
              },
              quantity: () => {
                return Evergage.DisplayUtils.pageElementLoaded(
                  ".cart-empty, .checkout-btn",
                  "html",
                ).then((ele) => {
                  return Evergage.resolvers.fromSelectorMultiple(
                    ".product-info .product-details .qty-card-quantity-count",
                  );
                });
              },
            },
          },
        },
      },
      {
        name: "order_confirmation",
        isMatch: () => /\/confirmation/.test(window.location.href),
        itemAction: Evergage.ItemAction.Purchase,
        catalog: {
          Product: {
            orderId: () => {
              return Evergage.DisplayUtils.pageElementLoaded(".order-number", "html").then(
                (ele) => {
                  return Evergage.resolvers.fromSelector(".order-number");
                },
              );
            },
            lineItems: {
              _id: () => {
                return Evergage.DisplayUtils.pageElementLoaded(
                  ".product-line-item line-item-quantity-info",
                  "html",
                ).then((ele) => {
                  return Evergage.resolvers.fromSelectorAttributeMultiple(
                    ".product-line-item .line-item-quantity-info",
                    "data-pid",
                  );
                });
              },
              price: () => {
                return Evergage.DisplayUtils.pageElementLoaded(
                  ".product-line-item .pricing",
                  "html",
                ).then((ele) => {
                  return Evergage.resolvers.fromSelectorAttributeMultiple(
                    ".product-line-item .pricing",
                    "data-pid",
                  );
                });
              },
              quantity: () => {
                return Evergage.DisplayUtils.pageElementLoaded(
                  ".product-line-item .qty-card-quantity-count",
                  "html",
                ).then((ele) => {
                  return Evergage.resolvers.fromSelectorAttributeMultiple(
                    ".product-line-item .qty-card-quantity-count",
                    "data-pid",
                  );
                });
              },
            },
          },
        },
      },
      {
        name: "login",
        action: "Login",
        isMatch: () =>
          /\/login/.test(window.location.href) &&
          window.location.hostname !== "community.northerntrailoutfitters.com",
        listeners: [
          Evergage.listener("click", "form[name='login-form'] button", () => {
            const email = Evergage.cashDom("#login-form-email").val();
            if (email) {
              Evergage.sendEvent({
                action: "Logged In",
                user: { attributes: { emailAddress: email } },
              });
            }
          }),
        ],
      },
      {
        name: "home",
        action: "Homepage",
        isMatch: () => /\/homepage/.test(window.location.href),
        contentZones: [
          { name: "home_hero", selector: ".experience-carousel-bannerCarousel" },
          {
            name: "home_sub_hero",
            selector: ".experience-carousel-bannerCarousel + .experience-component",
          },
          { name: "home_popup" },
        ],
      },
      {
        name: "community_login",
        action: "Community Login",
        isMatch: () =>
          window.location.hostname === "community.northerntrailoutfitters.com" &&
          /\/s\/login/.test(window.location.href),
        listeners: [
          Evergage.listener("click", ".loginButton", (event) => {
            const email = Evergage.cashDom("input[placeholder='Email']").val();
            if (email) {
              Evergage.sendEvent({
                action: "Community Log In",
                user: { attributes: { emailAddress: email } },
              });
            }
          }),
        ],
      },
      {
        name: "community_home",
        action: "Community Homepage",
        isMatch: () => {
          return (
            window.location.hostname === "community.northerntrailoutfitters.com" &&
            /^\/s\/?$/.test(window.location.pathname)
          );
        },
        listeners: [
          Evergage.listener("click", "li.topicItem", (event) => {
            const topicLabel = Evergage.cashDom(event.currentTarget)
              .find(".topicLabel")
              .text()
              .trim();
            if (topicLabel) {
              Evergage.sendEvent({ action: "Community Homepage - " + topicLabel });
            }
          }),
        ],
      },
    ],
  };
  const getProductsFromDataLayer = () => {
    if (window.dataLayer) {
      for (let i = 0; i < window.dataLayer.length; i++) {
        if (
          ((window.dataLayer[i].ecommerce && window.dataLayer[i].ecommerce.detail) || {}).products
        ) {
          return window.dataLayer[i].ecommerce.detail.products;
        }
      }
    }
  };
  Evergage.initSitemap(config);
});
```

<!-- document id=a6112b93775c25904ee6ab08b38e995659a86f1bb503d22ce43b2bc206feee22 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/server-side-campaigns-templates/einstein-decisions-server-side-template.md -->

# Einstein Decisions - Server-Side Template

When using Einstein Decisions in a template, a slightly different server-side code configuration is necessary for a server-side template than a Web template. This article describes the fundamental differences between the two types of templates concerning the following two critical parts of the template.

- What content zone or tag the bandit leverages for decision-making
- What data is returned on the promotion

## Global Web Template

### Content Zone or Tag Selection: context.contentZone

The Global Web Template leverages `context.contentZone` to determine which promotion content zone is to be evaluated for a decision by Einstein Decisions. The `context.contentZone` value maps to the targeted web content zone of the template, meaning the targeted web content zone serves the following two purposes.

- Determining where the Einstein Decisions template is allowed to render on the site
- Filtering which promotions are eligible to be returned by the template (only promotions with an asset that has a content zone or tag that maps to the targeted web content zone are eligible for decision-making)

To configure the targeted web content zone, you can use the **Content Zones in Template** selector in the Web Template Editor to select a single value or define a set of values for business users to pick from via a dropdown menu.

![Einstein Decisions Web contentZone](https://developer.salesforce.com/media/campaign-development/einstein-decisions-content-zone-web.png)

By leveraging `context.contentZone` in the template, you effectively restrict which promotions can be returned. Since the **Content Zones in Template** selector in the Web Template Editor only displays web content zones defined in the sitemap, only promotions with an asset tied to a web content zone are eligible to return.

### Campaign Response: Image URL and Promotion URL

The Global Web Template returns the primary data required for client-side rendering. In this case, the template is set to return just the image URL for the selected asset and the promotion URL. You can easily configure additional promotion attributes/information to return via the web template.

## Server-Side Template

### Content Zone or Tag Selection: ContentZoneLookup

The server-side iteration of the template gives you a little more flexibility. Since the **Content Zones in Template** selector leveraged in web templates is not available in the server-side template interface, use `ContentZoneLookup` instead of referencing `context.contentZone`. Unlike the web content zone selector, `ContentZoneLookup` is not restricted to only content zones defined in the sitemap. Instead, it enables a business user to select any content zone or tag value stored against a promotion asset or defined in the sitemap. The value that a business user selects will reflect the promotion content zone or tag that Einstein Decisions then leverages for real-time evaluation and decision-making.

### Campaign Response: Full Promotion

Since Marketing Cloud Personalization is not responsible for rendering the decision passed back via a server-side campaign, the Server-Side template is designed to return all promotion information for the selected promotion by default. You can easily restrict what is returned in the response if the complete promotion data is not required.

Additionally, since the complete promotion data is being returned, as opposed to asset-specific data like an image URL, a business user only needs to define a fallback promotion as opposed to a fallback promotion along with a fallback asset.

## Template Selection Based on Click Log Tracking

To properly train the contextual bandit, it is essential to ensure click log generation. The Einstein Decisions global web template automatically tracks click logs and view logs in web campaigns. However, only view logs are tracked automatically in server-side Einstein Decisions campaigns, while clicks require manual tracking.

This section outlines two approaches for ensuring the proper capture of click logs.

### Template Option 1: Return Selected Content Zone or Tag in the Template run() Function

This option requires `contentZone` to be set on the experience. You can set `contentZone` on the experience in server-side campaigns by returning the `contentZone` explicitly through the server-side template's `run` function.

The following code depicts an example template for this approach.

```typescript
import { ContextualBanditConfig, decide } from "corvus";
import { ItemReference, ContentZoneLookup } from "common";

export class PromotionSearchOptions implements Search<string> {
  search(context: GearLifecycleContext, searchString: string): ItemReference[] {
    if (!searchString) {
      return [];
    }
    const promos: Promotion[] = context.services.catalog.findByName(
      "Promotion",
      searchString,
    ) as Promotion[];
    return promos.reduce((allPromos: ItemReference[], promo: Promotion) => {
      const promoItem = {
        itemType: "Promotion",
        id: promo.id,
        label: promo.attributes["name"] != null ? promo.attributes["name"].value : promo.id,
      } as ItemReference;
      allPromos.push(promoItem);
      return allPromos;
    }, []);
  }
}

export class EinsteinDecisionsTemplate implements CampaignTemplateComponent {
  @lookupOptions(() => new ContentZoneLookup())
  assetContentZoneOrTag: string;

  @searchOptions((self) => new PromotionSearchOptions())
  @title("Optional Fallback Promotion Selector")
  @subtitle(`Search for a fallback promotion to return if there are no eligible promotions to return for the end user.
   If no fallback is selected, no promotion will be returned. (NOTE: This field is case-sensitive.)`)
  fallbackArm: ItemReference;

  run(context: CampaignComponentContext) {
    const banditConfig: ContextualBanditConfig = {
      maxResults: 1,
      contentZone: this.assetContentZoneOrTag,
      fallbackArms: this.fallbackArm ? [this.fallbackArm.id] : [],
    } as ContextualBanditConfig;
    const promotions: Promotion[] = decide(context, banditConfig, null) as Promotion[];
    return { promotions, contentZone: this.assetContentZoneOrTag };
  }
}
```

In the preceding template configuration, note that the selected `contentZone` in the template configuration screen gets applied to the experience. Therefore, for this campaign/experience to return, the inbound event request to Personalization must include a matching `contentZone` value on the `source` object. The campaign does not return if there is no matching `contentZone` value on the inbound event.

If the desired `contentZone` is unknown when sending an event request to Personalization, we recommend leveraging [Option 2](#template-option-2-modified-stat-event-leveraging-click-through-item-action), which allows you to avoid setting a `contentZone` on the campaign/experience to ensure that the campaign can return without a `contentZone` being specified on the `source` object on the inbound event.

The following code depicts the formatting of an example `stat` event using the preceding template.

```json
{
  "source": {
    "channel": "Server",
    "pageType": "Homepage"
  },
  "user": {
    "id": "sample user"
  },
  "campaignStats": [
    {
      "stat": "Click",
      "experienceId": "experience Id",
      "control": false,
      "catalog": {
        "Promotion": ["promotion Id"]
      }
    }
  ]
}
```

### Template Option 2: Modified Stat Event Leveraging Click Through Item Action

As mentioned in Option 1, using the template configuration that sets the `contentZone` via the `run` function means that the experience only returns when `contentZone` is present in the original event. If the `contentZone` is unknown at the campaign request time, you can use the following template configuration and ensure click log generation using a modified `stat` event that includes the `contentZone` leveraged in the campaign decision. The only difference between the following template and the preceding one is the `return` object of the `run` function.

```typescript
import { ContextualBanditConfig, decide } from "corvus";
import { ItemReference, ContentZoneLookup } from "common";

export class PromotionSearchOptions implements Search<string> {
  search(context: GearLifecycleContext, searchString: string): ItemReference[] {
    if (!searchString) {
      return [];
    }
    const promos: Promotion[] = context.services.catalog.findByName(
      "Promotion",
      searchString,
    ) as Promotion[];
    return promos.reduce((allPromos: ItemReference[], promo: Promotion) => {
      const promoItem = {
        itemType: "Promotion",
        id: promo.id,
        label: promo.attributes["name"] != null ? promo.attributes["name"].value : promo.id,
      } as ItemReference;
      allPromos.push(promoItem);
      return allPromos;
    }, []);
  }
}

export class EinsteinDecisionsTemplate implements CampaignTemplateComponent {
  @lookupOptions(() => new ContentZoneLookup())
  assetContentZoneOrTag: string;

  @searchOptions((self) => new PromotionSearchOptions())
  @title("Optional Fallback Promotion Selector")
  @subtitle(`Search for a fallback promotion to return if there are no eligible promotions to return for the end user.
   If no fallback is selected, no promotion will be returned. (NOTE: This field is case-sensitive.)`)
  fallbackArm: ItemReference;

  run(context: CampaignComponentContext) {
    const banditConfig: ContextualBanditConfig = {
      maxResults: 1,
      contentZone: this.assetContentZoneOrTag,
      fallbackArms: this.fallbackArm ? [this.fallbackArm.id] : [],
    } as ContextualBanditConfig;
    const promotions: Promotion[] = decide(context, banditConfig, null) as Promotion[];
    return { promotions };
  }
}
```

The following code depicts the formatting of an example `stat` event to ensure proper click log generation using the preceding template.

```json
{
  "source": {
    "channel": "Server",
    "pageType": "Homepage",
    "contentZones": ["content zone"]
  },
  "user": {
    "id": "sample user"
  },
  "itemAction": "Click Through",
  "catalog": {
    "Promotion": {
      "id": "promo"
    }
  },
  "campaignStats": [
    {
      "stat": "Click",
      "experienceId": "experience Id",
      "control": false,
      "catalog": {
        "Promotion": ["promotion Id"]
      }
    }
  ]
}
```

The preceding `stat` event includes the standard click campaign `stat` object that populates the clicks against the campaign and the promotion on the promoted item detail stat screen. This `stat` event is different from the `stat` event outlined in Option 1 in the following key ways.

- **`contentZone` included on the `source` object**: In [Option 1](#template-option-1-return-selected-content-zone-or-tag-in-the-template-run-function), the `contentZone` is set on the campaign/experience and is therefore not required in the `stat` event. In this option, since the `contentZone` is not set on the campaign/experience, it needs to be included on the `stat` event to allow for click log generation to support model training. The `contentZone` or tag selected in the template configuration for decisioning purposes is available on the campaign response object as the `assetContentZoneOrTag` value. The web developer configuring the `stat` event can easily reference that value to populate the `contentZone` value on the `stat` event.

- **`Click Through` Item Action**: This item action is only leveraged in this specific instance to track clicks on the promotion object. Paired with the `contentZone` on the `source` object, this item action causes click logs to be generated for model training.

When sent to Personalization, a single event has to include the campaign stat object and the `Click Through` item action object.

The `return` object in the first template sets the selected asset content zone or tag as the `contentZone` on the experience and campaign response object, while this template does not. Instead, it leaves the `contentZone` value blank.

<!-- document id=e988e9622c5961bde84a1b4082849b7c27e15a2791315ca32cc5e8736db222b5 url=/developer/current/en-us/personalization/personalization/guides/event-api/event-api-requests.md -->

# Event API Requests

The Personalization Event API uses standard HTTP methods and returns JSON-formatted responses to requests generated by the Sitemap and other Personalization event sources. The following sections describe the various Event API endpoints that enable you to interact with the Personalization platform.

## Send Event Data

Send event data to the Personalization dataset specified in the request.

### Method and Endpoint

`POST` `/api2/event/<dataset>`

### Request URL

`https://<accountName>.<instance>.evergage.com/api2/event/<dataset>`

### URL Parameters

| URL Parameter | Required? | Description                                                                                                                                                                                                                                            |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `accountName` | Yes       | The Personalization account name. You can find the `accountName` by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the account name is `demo`.        |
| `instance`    | Yes       | The Personalization instance identifier. You can find this value by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the instance identifier is `us-1`. |
| `dataset`     | Yes       | Name or identifier of the Personalization dataset you're sending data to.                                                                                                                                                                              |

### Supported Content Types

- `application/json`
- `application/x-www-form-urlencoded`

### Examples

Consider the following as sample event data that you would like to send to Personalization.

```json
{
  "action": "hello world",
  "user": {
    "id": "testuser"
  }
}
```

You can send this event data to Personalization as a JSON payload by [minifying](https://www.npmjs.com/package/json-minify) the event data to remove whitespaces, including it in the body of your API request, and setting the `Content-Type` to `application/json`.

```bash
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"action":"hello world","user":{"id":"testuser"}}' \
     "https://<accountName>.<instance>.evergage.com/api2/event/<dataset>"
```

**important:** Don’t make `POST` requests with `Content-Type: application/json` from an environment that checks for Cross-Origin Resource Sharing (CORS), such as a web browser.

When using `Content-Type: application/x-www-form-urlencoded`, the event data must be minified and then base64-encoded. Minifying the preceding example event data JSON gives you the following single-line JSON string.

```json
{ "action": "hello world", "user": { "id": "testuser" } }
```

Base64-encoding the above JSON string gives you the value `eyJhY3Rpb24iOiJoZWxsbyB3b3JsZCIsInVzZXIiOnsiaWQiOiJ0ZXN0dXNlciJ9fQ==`. You can then pass this value via the `event` key, as shown in the following example request.

```bash
curl -X POST \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'event=eyJhY3Rpb24iOiJoZWxsbyB3b3JsZCIsInVzZXIiOnsiaWQiOiJ0ZXN0dXNlciJ9fQ==' \
     "https://<accountName>.<instance>.evergage.com/api2/event/<dataset>"
```

## Send Event Data Using a GET Request

Send event data to the Personalization dataset specified in the request.

### Method and Endpoint

`GET` `/api2/event/<dataset>`

The event data you send in `GET` requests must be minified, base64-encoded, and passed via the `event` query parameter in the request URL.

### Request URL

`https://<accountName>.<instance>.evergage.com/api2/event/<dataset>?event=<base64-encoded-minified-event>`

### URL Parameters

| URL Parameter                   | Required? | Description                                                                                                                                                                                                                                            |
| ------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `accountName`                   | Yes       | The Personalization account name. You can find the `accountName` by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the account name is `demo`.        |
| `instance`                      | Yes       | The Personalization instance identifier. You can find this value by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the instance identifier is `us-1`. |
| `dataset`                       | Yes       | Name or identifier of the Personalization dataset you're sending data to.                                                                                                                                                                              |
| `base64-encoded-minified-event` | Yes       | The minified and base64-encoded event data string.                                                                                                                                                                                                     |

### Example

Consider the following as sample event data that you would like to send to Personalization.

```json
{
  "action": "hello world",
  "user": {
    "id": "testuser"
  }
}
```

To send this event, minify the JSON event data, base64-encode the resulting string, and include it in the event parameter of a `GET` request, as shown in the following example.

```bash
curl -X GET 'https://<accountName>.<instance>.evergage.com/api2/event/<dataset>/event=eyJhY3Rpb24iOiJoZWxsbyB3b3JsZCIsInVzZXIiOnsiaWQiOiJ0ZXN0dXNlciJ9fQ=='
```

You can also send the `GET` request via a web browser by accessing the request URL directly in your browser.

**note:** You can use `GET` requests as an alternative to using `POST` requests for sending event data to your Personalization datasets, if necessary.

## Send Event Data via Trusted Channel

The Personalization Event API provides a dedicated endpoint sending events that use _trusted_ `Server` channels. The API call must be authenticated with a valid API token that is permitted to send events. The API token must be provided via the `Authorization` header according to the HTTP basic authentication scheme. For more information about creating and configuring an API token in Personalization, see [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm).

**note:** - For datasets created after January 28, 2021, the campaign targeting rule is set to `channel: Server` by default. To return server-side campaigns using the Event API, events must be sent via a trusted server channel. For more information on the implications of using or removing the `channel: Server` rule, refer to the [Server-Side Templates](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/server-side-campaigns-templates.md#determine-campaign-identity--authentication-requirements) documentation.
- To add authentication to server-side campaigns for datasets created before January 28, 2021, [Create a Support Case](https://help.salesforce.com/s/articleView?language=en_US&id=sf.workcom_contact_support.htm&type=5).

### Supported Content Types

- `application/json`

### Method and Endpoint

`POST` `/api2/authevent/<dataset>`

### Request URL

`https://<accountName>.<instance>.evergage.com/api2/authevent/<dataset>`

### URL Parameters

| URL Parameter | Required? | Description                                                                                                                                                                                                                                            |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `accountName` | Yes       | The Personalization account name. You can find the `accountName` by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the account name is `demo`.        |
| `instance`    | Yes       | The Personalization instance identifier. You can find this value by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the instance identifier is `us-1`. |
| `dataset`     | Yes       | Name or identifier of the Personalization dataset you're sending data to.                                                                                                                                                                              |

### Supported Content Types

`application/json`

### Authorization

`Authorization: Basic <base64-encoded-API-token>`

The Event API uses API tokens to authenticate requests. Your API token must be a strict Base64 encoding of your API Key ID and its API Secret Key, separated by a colon. You can use an existing API token with required permissions or request an administrator to create one via the Personalization UI at **Security** > **API Tokens** > **Create Token**. For more information about API tokens, see [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm).

Alternatively, if you use [cURL](https://curl.se/docs/manpage.html) to interact with the API, you can send your API Key ID and its API Key Secret using the `-u "apiKeyId:apiKeySecret"` command-line option. cURL automatically converts the `apiKeyId:apiKeySecret` pair into a Base64-encoded string and adds `Authorization: Basic <base64-encoded-API-token>` to the request header.

### Example

Consider the following as sample event data that you would like to send to Personalization.

```json
{
  "action": "hello world",
  "source": {
    "channel": "Server"
  },
  "user": {
    "id": "testuser"
  }
}
```

You can send this event data via the trusted channel via a `POST` request to the dedicated endpoint, as shown in the following example request. Ensure that you minify the event JSON data into a single line by removing all whitespaces before sending it via the `POST` request.

```bash
curl -X POST \
     -H 'Content-Type: application/json' \
     -u "apiKeyId:apiKeySecret" \
     -d '{"action":"hello world","source":{"channel":"Server"},"user":{"id":"testuser"}}' \
     "https://<accountName>.<instance>.evergage.com/api2/authevent/<dataset>"
```

## See Also

- [_Salesforce Help_: Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm)
- [_Salesforce Help_: Create a Support Case](https://help.salesforce.com/s/articleView?id=sf.workcom_contact_support.htm)
- [_External Link_: npm: Minify JSON](https://www.npmjs.com/package/json-minify)
- [_External Link_: cURL Man Page](https://curl.se/docs/manpage.html)

<!-- document id=ab40b9e7d94caf483faf698bf83c4b3554e263539a407d5053f0f00a46b37c4d url=/developer/current/en-us/personalization/personalization/guides/event-api/event-api-responses.md -->

# Event API Responses

Requests sent to the Event API return JSON that contains information about any campaigns that are returned. A response from the Event API has the following structure.

```json
{
    "campaignResponses": CampaignResponse[],
    "compiledCampaignTemplates": CompiledCampaignTemplate[],
    "campaignExplanations": CampaignExplanation[],
    "errorCode": number,
    "resolvedUserId": string,
    "persistedUserId": object,
    "eventDetails": eventDetails
}
```

| Key                         | Value                        | Description                                                                                                                                                                                                                                                                                                                |
| --------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `campaignResponses`         | `CampaignResponse[]`         | An array of all campaigns returned in the event. For more information, see [The CampaignResponse Object](#the-campaignresponse-object).                                                                                                                                                                                    |
| `compiledCampaignTemplates` | `CompiledCampaignTemplate[]` | An array of all campaign templates returned in the event. For more information, see [The CompiledCampaignTemplates Object](#the-compiledcampaigntemplates-object).                                                                                                                                                         |
| `errorCode`                 | Number                       | The error code. Possible values are: <ul><li> 0 : Success </li><li> 1 : Missing Encrypted `UserId` Parameter </li><li> 2 : Invalid Encrypted `UserId` Parameter</li><li>3 : Busy</li><li>4: Anonymous ID Correction</li><li>5: Invalid Event</li> </ul>                                                                    |
| `resolvedUserId`            | String                       | The `primaryId` of the resolved User. The `primaryId` is only returned if the **Pipeline Identity Resolution** feature is enabled for the tenant. For more information, see [User Identity Mapping](https://developer.salesforce.com/docs/marketing/personalization/web-integration/user-identity-mapping.md).                                                                          |
| `persistedUserId`           | Object                       | An object containing the encrypted user ID of the user. The Event API returns the `persistedUserId` only if **Pipeline Identity Resolution** isn’t enabled for the tenant and a primary user ID is specified in the event. For more information, see [User Identity Mapping](https://developer.salesforce.com/docs/marketing/personalization/web-integration/user-identity-mapping.md). |
| `eventDetails`              | `eventDetails`               | An object containing the event received by the server. This object is only returned if `debug.explanations` was sent with the event and the event was authenticated.                                                                                                                                                       |

## The CampaignResponse Object

The `CampaignResponse` object contains data associated with the campaigns returned from an event.

```json
{
    "type": string,
    "campaignId": string,
    "campaignName": string,
    "campaignType": string,
    "experienceId": string,
    "experienceName": string,
    "experienceSourceCode": string,
    "state": string,
    "displayMode": string,
    "redirectUrl": null,
    "saveParameters": boolean,
    "hidePageBeforeRedirect": boolean,
    "campaignJavascriptContent": null,
    "javascriptContent": null,
    "userGroup": string,
    "googleAnalyticsConfig": null,
    "messages": [],
    "pageChanges": [],
    "templateNames": string[],
    "serverSideMessages": ServerSideMessage[],
    "payload": payload
}
```

| Key                         | Value                 | Description                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                      | String                | The type of campaign returned. The value of `type` is `"c"` for server-side campaigns and `"ng"` for web campaigns.                                                                                                                                                                                                                                                                                        |
| `campaignId`                | String                | The ID of the campaign returned.                                                                                                                                                                                                                                                                                                                                                                           |
| `campaignName`              | String                | The name of the campaign returned.                                                                                                                                                                                                                                                                                                                                                                         |
| `campaignType`              | String                | The type of the campaign returned. The value of `campaignType` is `"ServerSide"` for server-side campaigns and `"Web"` for web campaigns.                                                                                                                                                                                                                                                                  |
| `experienceId`              | String                | The ID of the experience returned.                                                                                                                                                                                                                                                                                                                                                                         |
| `experienceName`            | String                | The name of the experience returned.                                                                                                                                                                                                                                                                                                                                                                       |
| `state`                     | String                | The state of the campaign returned. The value of `state` can be `"Published"`, `"Disabled"`, or `"Testing"` depending on the campaign state.                                                                                                                                                                                                                                                               |
| `displayMode`               | String                | **Deprecated**. This object is only returned for server-side campaigns and its value is always `"Personalized"`.                                                                                                                                                                                                                                                                                           |
| `redirectUrl`               | Null                  | **Deprecated**. This object is only returned for server-side campaigns.                                                                                                                                                                                                                                                                                                                                    |
| `saveParameters`            | Boolean               | **Deprecated**. This object is only returned for server-side campaigns and is always set to `false`.                                                                                                                                                                                                                                                                                                       |
| `hidePageBeforeRedirect`    | Boolean               | **Deprecated**. This object is only returned for server-side campaigns and is always set to `false`.                                                                                                                                                                                                                                                                                                       |
| `campaignJavascriptContent` | Null                  | **Deprecated**. The `campaignJavascriptContent` object is always set to `null`.                                                                                                                                                                                                                                                                                                                            |
| `javascriptContent`         | Null                  | **Deprecated**. This object is only returned for server-side campaigns and is always set to `null`.                                                                                                                                                                                                                                                                                                        |
| `userGroup`                 | String                | The user group of the campaign experience returned. The value of `userGroup` can be either `"Default"` or `"Control"`.                                                                                                                                                                                                                                                                                     |
| `googleAnalyticsConfig`     | Null                  | **Deprecated**. This object is only returned for server-side campaigns and is always set to `null`.                                                                                                                                                                                                                                                                                                        |
| `messages`                  | Empty array           | **Deprecated**. This object is only returned for server-side campaigns and is always set to `[]`.                                                                                                                                                                                                                                                                                                          |
| `pageChanges`               | Empty array           | **Deprecated**. This object is only returned for server-side campaigns and is always set to `[]`.                                                                                                                                                                                                                                                                                                          |
| `templateNames`             | String array          | An array of the template names used in the experience. This object is only returned for web campaigns.                                                                                                                                                                                                                                                                                                     |
| `serverSideMessages`        | `ServerSideMessage[]` | An array of messages returned for a server-side campaign. This object is only returned for server-side campaigns. The event **must** be sent with `source.channel` set to `"Server"` in order to return `serverSideMessages`. For more information, see [ServerSideMessage object](#the-serversidemessage-object).                                                                                         |
| `payload`                   | `payload`             | The payload object that the campaign returns. The `payload` object always includes the `campaign`, `experience`, and `userGroup` fields, along with other user defined fields. For more information, see [Template Server Typescript](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/templates/template-server-typescript.md). **Note:** The value of `campaignResponse.payload.userGroup` can either be `"Test"` or `"Control"`. |

## The ServerSideMessage Object

The `ServerSideMessage` object contains data associated with `serverSideMessages` returned in a `campaignResponse`.

For server-side campaigns, an array of `ServerSideMessage` objects is returned that contains information about the data returned for the server-side campaign message. The event **must** be sent with `source.channel` set to `"Server"` in order to return `serverSideMessages`. For more information on configuring server-side campaigns, see [Server-Side Campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_server_side_campaign.htm).

```javascript
{
    "type": string,
    "id": string,
    "data": string,
    "targetName": string,
    "containsDynamicContent": boolean,
    "promotedItemKeys": PromotedItem[] | null,
    "campaignState": string,
    "dataMap": dataMap
}
```

| Key                      | Value                                       | Description                                                                                                                                                                                                                      |
| ------------------------ | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                   | String                                      | The type of message that is returned. For a `ServerSideMessage`, the `type` is always `"evg_md"`.                                                                                                                                |
| `id`                     | String                                      | The ID of the message that is returned.                                                                                                                                                                                          |
| `data`                   | String                                      | **Deprecated**. Its value is always `"{}"`.                                                                                                                                                                                      |
| `targetName`             | String                                      | The name of the target for the `ServerSideMessage`.                                                                                                                                                                              |
| `containsDynamicContent` | Boolean                                     | The value returned is `true` if the message contains any dynamic content, and `false` if the message doesn’t contain dynamic content.                                                                                            |
| `promotedItemKeys`       | `PromotedItem[] \| null`                    | If the message contains promoted items, `promotedItemKeys` is an array of promoted items. Otherwise its value is `null`. Each `PromotedItem` returned contains the type of the item returned and the `_id` of the item returned. |
| `campaignState`          | `"Published"`, `"Disabled"`, or `"Testing"` | The state of the campaign returned.                                                                                                                                                                                              |
| `dataMap`                | `dataMap`                                   | An object containing the key value pairs defined in the campaign.                                                                                                                                                                |

### Example Values

The following is an example of a value returned in the `promotedItemKeys` object:

```javascript
{
    type: "p",
    _id: "123"
}
```

The following is an example of a value returned in the `dataMap` object:

```javascript
dataMap: {
    "myText": "helloWorld",
    "myNumber": "1",
    "myPromotedContent": [
        {
            "type": "p",
            "_id": "123"
        },
        {
            "type": "p",
            "_id": "456"
        }
    ]
}
```

For keys with type "Promoted Content", the full value of each item is returned unless the "Item IDs only" option is enabled in the message settings. For more information on configuring server-side campaigns and the returned `dataMap` object, see [Server-Side Campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_server_side_campaign_create.htm).

## The CompiledCampaignTemplates Object

The `CompiledCampaignTemplates` object contains data associated with `campaignTemplates` returned in an event.

An event response returns an array of any `compiledCampaignTemplates` used in a `campaignResponse`. The `compiledCampaignTemplates` object contains information about the campaign templates.

```javascript
{
    "id": string,
    "name": string | null,
    "bundle" string
}
```

| Key      | Value            | Description                                                                                                         |
| -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| `id`     | String           | The ID of the template.                                                                                             |
| `name`   | String or `null` | The name of the template.                                                                                           |
| `bundle` | String           | The stringified [client-side code](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/web-campaigns-templates.md) used to render the template. |

## The CampaignExplanations Object

The `CampaignExplanations` Object contains data associated with `campaignExplanations` returned in an event.

The `campaignExplanations` object returns in an event only if `debug.explanations` is `true` in the event payload. It contains additional information about why campaigns did or didn’t return in the event response. It’s only returned if the event request is authenticated.

```javascript
{
    "class": string,
    "campaignId": string,
    "campaignName": string,
    "experienceId": string,
    "experienceName": string,
    "messageId": string,
    "explanationMessage": string,
    "context": string
}
```

| Key                  | Value  | Description                                                                                                                                 |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `class`              | String | Information of the type of explanation that is returned.                                                                                    |
| `campaignId`         | String | The ID of the campaign that the explanation is for.                                                                                         |
| `campaignName`       | String | The name of the campaign that the explanation is for.                                                                                       |
| `experienceId`       | String | The ID of the experience that the explanation is for.                                                                                       |
| `experienceName`     | String | The name of the experience that the explanation is for.                                                                                     |
| `messageId`          | String | The ID of the message that the explanation is for.                                                                                          |
| `explanationMessage` | String | A message containing the reason for not returning the campaign in the response.                                                             |
| `context`            | String | A string containing the campaign name, campaign ID, experience name, and experience ID for the message that isn't returned in the response. |

## See Also

- [_Salesforce Help_: Server-Side Campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_server_side_campaign.htm)

<!-- document id=32ae50f51b2b5c286148892d7430bcaae923553b66615f1e55065e4486476023 url=/developer/current/en-us/personalization/personalization/guides/event-api/event-options-evergage.md -->

# Event Options in the Evergage Namespace

The following code sample details the event options available in the `Evergage` namespace in the Personalization module of the Salesforce Interactions SDK.

```javascript
{
    action: string,
    itemAction: string,
    consents: Consent[],
    debug: {
        explanations: boolean,
        testMessages: string
    },
    flags: {
       noCampaigns: boolean,
       doNotTrack: boolean,
       pageView: boolean,
       nonInteractive: boolean
    },
    source: {
        channel: string,
        pageType: string,
        url: string,
        urlReferrer: string,
        locale: string,
        contentZones: string[],
        time: number,
        userAgent?: string,
        clientIp?: string,
        operatingSystem?: string
        operatingSystemVersion?: string,
        device?: string,
        surveyId?: string,
        surveyStartTime?: string
    },
    user: {
        id: string,
        attributes: {
            [key: string]: string | number | boolean
        },
        profileObjects: {
            [profileObjectType: string]: ProfileObject[]
        },
    },
    account: {
        id: string,
        domain: string,
        attributes: {
            [key: string]: string | number | boolean
        },
    },
    catalog: {
        <ItemType>: {
            [key: string]: string | number | boolean | object
        }
    },
    order: {
        <ItemType>: {
            orderId: string,
            totalValue: number,
            currency: string
            lineItems: LineItem[]
        }
    },
    cart: {
        singleLine: {
            <ItemType>: LineItem
        },
        complete: {
            <ItemType>: LineItem[]
        }
    },
    campaignStats: CampaignStat[],
    performance: {
        sdkLoadTime: number,
        pageLoadTime: number,
        sdkParseTime: number,
        networkTime: number,
        sdkDnsTime: number,
        eventDnsTime: number,
        downloadTime: number
    }
}
```

| Event Property | Value Type | Description                                                         |
| -------------- | ---------- | ------------------------------------------------------------------- |
| `action`       | String     | Name of the event. Used for segmentation, targeting, and reporting. |
| `itemAction`   | String     | Defines the action taken on a catalog item.                         |

## The consent Object

The `Consent` field accepts an array of consent objects for the user. The following table describes the various properties available in the `consent` object.

| Property   | Value Type | Description                                                  |
| ---------- | ---------- | ------------------------------------------------------------ |
| `purpose`  | String     | The purpose for the consent. For example, `Personalization`. |
| `provider` | String     | The consent provider                                         |
| `status`   | String     | The consent status. For example, `OptIn` or `OptOut`         |

## The debug Object

The `debug` object contains fields that help investigate issues that could arise when developing campaigns.

The following table describes the various properties available in the `debug` object.

| Property       | Value Type | Description                                                                                                                                                                                                                                                                             |
| -------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `explanations` | Boolean    | If `true`, then return additional information in the response about why campaigns did or didn’t render. Requires authentication.                                                                                                                                                        |
| `testMessages` | String     | A comma-separated list of campaign experience IDs to be forced to return in the event, ignoring rules that would otherwise prevent the campaign from returning. Alternatively, you can use the string value `true` to return all campaigns in testing mode but all rules are respected. |

## The flags Object

The `flags` object contains properties that alter default event processing. By default, all flags are `false` if not present on the event.

The following table describes the various properties available in the `flags` object.

| Property         | Value Type | Description                                                                                                                                                      |
| ---------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `noCampaigns`    | Boolean    | If `true`, don’t return campaigns in the response.                                                                                                               |
| `pageView`       | Boolean    | If `true`, indicates that the event was triggered from a page load.                                                                                              |
| `nonInteractive` | Boolean    | If `true`, a visit isn’t created (or updated) for the given user in the event. Additionally, no visit referrer nor originating referrer is created for the user. |
| `doNotTrack`     | Boolean    | If `true`, the event data is sent to the server but not processed.                                                                                               |

## The source Object

The `source` object contains properties that help describe where an event is coming from.

The following table describes the various properties available in the `source` object.

| Property                 | Value Type | Description                                                                                                                                                                            |
| ------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `channel`                | String     | The originating source of the event (For example, `Web`, `MobileApp`, `CallCenter`).                                                                                                   |
| `application`            | String     | The originating application level source of the event (For example, `ReactApp`, `3rdParty`, `ReactNative`)                                                                             |
| `pageType`               | String     | The type of page from which you’re sending the event (For example, `PDP`, `Blog`, `Pricing`).                                                                                          |
| `url`                    | String     | The URL of the page from which you’re sending the event.                                                                                                                               |
| `urlReferrer`            | String     | The previous URL visited by the user. `urlReferrer` is populated from `document.referrer` by default on the web. It can be overwritten in the sitemap to any other value if necessary. |
| `locale`                 | String     | The locale of the current page, as defined by ISO 639 alpha-2 language codes and ISO 3166 alpha-2 country codes (For example, `en_US`, `de_DE`).                                       |
| `contentZones`           | `string[]` | An array of content zones on the current page.                                                                                                                                         |
| `configVersion`          | Number     | Version number of the configuration for the SDK.                                                                                                                                       |
| `time`                   | Number     | The date and time of the event, in milliseconds elapsed since the UNIX epoch. This field is optional and is auto-populated with the current time if null.                              |
| `userAgent`              | String     | The user agent for the event. `userAgent` is populated automatically but can be overwritten if necessary                                                                               |
| `clientIp`               | String     | The IP Address sending the event. `clientIp` is populated automatically but can be overwritten if necessary                                                                            |
| `operatingSystem`        | String     | Only applicable for mobile events.                                                                                                                                                     |
| `operatingSystemVersion` | String     | Only applicable for mobile events.                                                                                                                                                     |
| `device`                 | String     | Only applicable for mobile events.                                                                                                                                                     |
| `surveyId`               | String     | The ID of the survey being submitted. `surveyId` is populated automatically for events sent through the Survey Gear                                                                    |
| `surveyStartTime`        | String     | The start time of the survey being submitted. `surveyStartTime` is populated automatically for events sent through the Survey Gear                                                     |

## The user Object

The `user` object describes the user associated with an event.

The following table describes the various properties available in the `user` object.

| Property         | Value Type                                         | Description                                                                                                                                                                 |
| ---------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | String                                             | The ID of a known user.                                                                                                                                                     |
| `encryptedId`    | String                                             | The encrypted ID returned from an event that contains the ID field. Encrypted IDs are returned in the response to events that provide a `user.id`.                          |
| `attributes`     | `{ [key: string]: string \| number \| boolean }`   | Key-value pairs that are stored as metadata on the user. These attributes must be defined in the platform.                                                                  |
| `profileObjects` | `{ [profileObjectType: string]: ProfileObject[] }` | Key-value pairs of profile objects that are stored as metadata on the user. Profile objects, their attributes, and related catalog objects must be defined in the platform. |

## The account Object

The `account` object describes the account associated with an event.

The following table describes the various properties available in the `account` object.

| Property     | Value Type                                       | Description                                                                                                   |
| ------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `id`         | String                                           | The ID of an account.                                                                                         |
| `attributes` | `{ [key: string]: string \| number \| boolean }` | Key-value pairs that are stored as metadata on the account. These attributes must be defined in the platform. |

## The catalog Object

The `catalog` object describes item data associated with the given `itemAction` and is used for actions pertaining to items in the catalog. For instance, the following `catalog` object provides the item being viewed when sending the item action "View Item".

```javascript
{
    itemAction: Evergage.ItemAction.ViewItem,
    catalog: {
        <ItemType>: {
            [key: string]: string | number | boolean | object
        }
    },
    ...
}
```

### The location Object

You can use the `location` object to send location data on a `catalog` object via the Event API or using the Sitemap. The following is an example of how you to structure a `catalog` object to include location data.

```json
"catalog": {
        "Product": {
            "_id": "test_product_1",
            "name": "test product name 1 ",
            "location": {
                "city": "Boston",
                "postalCode": "02215",
                "countryNumericCode": "840",
                "stateProvinceCode": "MA",
                "longlat": [-71.0871357, 42.3610235]
            }
        }
    }
```

The following examples depict sending data for locations outside the US.

```json
"catalog": {
        "Product": {
            "_id": "test_product_2",
            "name": "test product name 2",
            "location": {
                "city": "Melbourne",
                "postalCode": "3005",
                "countryNumericCode": "036",
                "stateProvinceCode": "VIC",
                "longlat": [144.963058, -37.813629]
            }
        }
    }
```

```json
"catalog": {
        "Product": {
            "_id": "test_product_3",
            "name": "test product name 3",
            "location": {
                "city": "Tokyo",
                "postalCode": "100-0004",
                "countryNumericCode": "392",
                "stateProvinceCode": "13",
                "longlat": [139.691711, 35.689487]
            }
        }
    }
```

## The order Object

The `order` object describes order data associated with the given `itemAction` and is used for Purchase actions.

The `order` object has the following structure.

```javascript
{
    ...
    order: {
        <ItemType>: {
            orderId: string,
            totalValue: number,
            currency: string
            lineItems: LineItem[]
        }
    },
    ...
}
```

The following table describes the properties that an `order` object accepts.

| Property     | Value Type   | Description                                                                                  |
| ------------ | ------------ | -------------------------------------------------------------------------------------------- |
| `orderId`    | String       | ID of the purchased order.                                                                   |
| `currency`   | String       | Optional currency code of purchase. Defaults to the dataset's configured currency if `null`. |
| `totalValue` | Number       | Optional total value for purchase. Defaults to the sum of line items quantity \* price.      |
| `lineItems`  | `LineItem[]` | List of purchased line items.                                                                |

### Line Item

A `LineItem` represents a single item in a cart and/or transaction. A `LineItem` object has the following structure.

```javascript
    {
        _id: string,
        price: number,
        quantity: number
    }
```

## The cart Object

The `cart` object describes cart data associated with the given `itemAction` and has the following structure.

```javascript
{
    ...
    cart: {
        singleLine: {
            <ItemType>: LineItem
        },
        complete: {
            <ItemType>: LineItem[]
        }
    }
    ...
}
```

The following table describes the properties a `cart` object accepts.

| Property     | Value Type   | Description                                                                                                                                                                                       |
| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `singleLine` | `LineItem`   | Used for `Add To Cart` and `Update Line Item` actions. `Add To Cart` adds the quantity to any existing matching items. `Update Line Item` overwrites the quantity of any existing matching items. |
| `complete`   | `LineItem[]` | Used to update the state of the cart in Personalization, setting its content to the provided line items. Previous cart contents are replaced.                                                     |

Additionally, a user's cart can be emptied by sending an event with an empty array of `LineItems`.

```javascript
{
  cart: {
    complete: {
      Product: [];
    }
  }
}
```

For more information, refer to the [LineItem](#line-item) documentation.

## The campaignStats Object

You can use the `campaignStats` object to track campaign statistics for an associated event.

For more information on sending campaign statistics on the web, refer to the [Campaign Stats Tracking](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/templates/campaign-stats-tracking.md) documentation.

The `campaignStats` object has the following structure.

```javascript
{
    ...
    {
        campaignStats: CampaignStat[]
    }
    ...
}
```

### CampaignStat

The `CampaignStat` object has the following structure.

```javascript
{
    experienceId: string,
    stat: "Impression" | "Click" | "Dismissal",
    control: boolean,
    catalog: {
        <ItemType>: string[]
    }
}
```

The following table describes the properties a `CampaignStat` object accepts.

| Property       | Value Type                               | Description                                                                                                    |
| -------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `experienceId` | String                                   | The experience ID of the campaign on which the given statistic is being tracked                                |
| `stat`         | `"Impression" \| "Click" \| "Dismissal"` | The type of statistic being tracked.                                                                           |
| `control`      | Boolean                                  | If `true`, the statistic is tracked for the control group of the given experience.                             |
| `catalog`      | `{ <ItemType>: string[] }`               | A mapping of catalog item types to a list of corresponding item IDs on which to attribute the given statistic. |

The following is an example of a mapping of catalog item types.

```javascript
...
catalog: {
    Product: ["product1", "product2"]
}
...
```

## The performance Object

The `performance` object has properties that measure loading, parsing, and network performance.

The following table describes the various properties available in the `performance` object.

| Property       | Value Type | Description                                                                    |
| -------------- | ---------- | ------------------------------------------------------------------------------ |
| `sdkLoadTime`  | Number     | (Web SDK) Time, in milliseconds, for the network to load the web SDK.          |
| `pageLoadTime` | Number     | (Web SDK) Time, in milliseconds, for the DOM to load.                          |
| `sdkParseTime` | Number     | (Web SDK) Time, in milliseconds, for the beacon to be parsed during page load. |
| `networkTime`  | Number     | (Web SDK) Time, in milliseconds, for the previous request to return.           |
| `sdkDnsTime`   | Number     | (Web SDK) Time, in milliseconds, to perform resolution of SDK's CDN domain.    |
| `eventDnsTime` | Number     | (Web SDK) Time, in milliseconds, to resolve account-specific domain.           |
| `domLoadTime`  | Number     | (Web SDK) Time, in milliseconds, for the DOM to finish loading.                |

<!-- document id=02f85a307914176ddc549159227663192004c0afaf8b22b3af2145b5856c1489 url=/developer/current/en-us/personalization/personalization/guides/web-integration/example-sitemaps.md -->

# Example Sitemaps

The following is a list of example Personalization Sitemaps we've created for different types of business websites that depict how you could approach designing a Sitemap for your Personalization implementation. The JavaScript and HTML code in these example Sitemaps are for reference purposes only but can give you a head start in developing the Sitemap for your implementation.

**important:** The sitemap code examples in these articles are only for demonstration purposes. Avoid copying sample code into your Sitemap Editor as it is built around example scenarios that can differ from your implementation's goals and use cases.

- [B2B](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps/b2b.md)
- [Ecommerce](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps/ecommerce.md)
- [Financial Services](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps/financial-services.md)

<!-- document id=d41ac3ed20343c3bb3671356d8dcf9d1f04759e9cc921edb14c74466260ce162 url=/developer/current/en-us/personalization/personalization/guides/web-integration/example-sitemaps/financial-services.md -->

# Financial Services

The following code sample depicts sitemap code for an imaginary implementation of Marketing Cloud Personalization on the Cumulus Financial Services website `https://www.cumulusfinserv.com/`. This sitemap code isn’t exhaustive and maps only key areas valuable for demonstrating an example implementation of Personalization. The primary focus of this sitemap code is to depict how to approach designing a Catalog for websites offering financial services.

For financial services implementations, we recommend using the Product catalog type as showcased in this example. In order to use this catalog type, we add a default price and quantity for each Product when creating line items as that data is not typically present on financial services Product Detail Pages (PDPs). Then on the forms associated with PDPs, we create a checkout flow and fire a `Purchase` interaction when the last step of a form is clicked. We don't recommend using a custom catalog object type as it doesn't as easily allow for conversion tracking. It's also harder to illustrate ownership when using a non-Product catalog type.

**important:** The sitemap code examples in this article are only for demonstration purposes. Avoid copying sample code into your Sitemap Editor as it is built around example scenarios that can differ from your implementation's goals and use cases.

## Example Sitemap for the SalesforceInteractions Namespace

```javascript
// This helper function is used help with the Purchase flow and returns an array of lineItems
function handleLineItems() {
    let itemId;
    if (window.localStorage.getItem('lastAddToCart')) {
        itemId = window.localStorage.getItem('lastAddToCart');
    }
    let purchaseLineItems = [];
    if (itemId != null) {
        let lineItem = {
            catalogObjectType: "Product",
            catalogObjectId: itemId,
            price: 1, 
            quantity: 1
        };
        purchaseLineItems.push(lineItem);
    }
    return purchaseLineItems;
}
/* 
 * This helper function handles adds to cart, adds the last carted item to local storage,
and sets a user attribute
 * called "lastAddToCart". This attribute can used for campaigns or recipe purposes. 
*/
function handleAddToCart(){
    let cartedItem = SalesforceInteractions.mcis.getLastPathComponentWithoutExtension(window.location.href).toUpperCase();
    window.localStorage.setItem("lastAddToCart", cartedItem);
    SalesforceInteractions.sendEvent({
        user: {
            attributes: {
                lastAddToCart: cartedItem
            }
        },
        interaction: {
            name: SalesforceInteractions.CartInteractionName.AddToCart,
            lineItem: {
                catalogObjectType: "Product",
                catalogObjectId: cartedItem,
                price: 1,
                quantity: 1
            }
        }
    })
}
/* This helper function passes in data from a form interaction and converts it into a proper actionEvent.
 * It also pulls all the possible selectors for form inputs to make sure they get scraped
 * to the correct user attributes.
*/
function handleFormInteraction({ interactionName, user = {}, order = {} }) {
    const actionEvent = {
        user: {
            ...user
        },
        interaction: {
            name: interactionName,
            order: {
                ...order
            }
        }
    };
    actionEvent.user.attributes = {
        firstName: SalesforceInteractions.cashDom("#firstName, input[name='firstName'], #form-appointment-first-name,
         #form-advisor-first-name, #form-advisor-first-name").val(),
        lastName: SalesforceInteractions.cashDom("#lastName, input[name='lastName'], #form-appointment-last-name,
         #form-advisor-last-name").val(),
        emailAddress: SalesforceInteractions.cashDom("#email, input[name='email'], #form-appointment-email,
         #form-advisor-email").val(),
        zipcode: SalesforceInteractions.cashDom("#zip, input[name='postal'], #form-appointment-zip, #form-advisor-zip,
         #form-application-zip").val(),
        existingCustomer: SalesforceInteractions.cashDom("select.form-control option[selected], #form-appointment-existing,
         #form-advisor-existing").val(),
        phone: SalesforceInteractions.cashDom("input[name='phone'], #form-application-phone").val(),
        companyName: SalesforceInteractions.cashDom("#form-appointment-company-name, #form-advisor-company-name").val(),
        over18: SalesforceInteractions.cashDom("#inlineAge:checked").val(),
        usCitizen: SalesforceInteractions.cashDom("#inlineCitizen:checked").val(),
        birthday: SalesforceInteractions.cashDom("#datepicker, input[name='birthday']").val(),
        addressLine1: SalesforceInteractions.cashDom("input[name='addr1'], #form-application-address-01").val(),
    }
    SalesforceInteractions.sendEvent(actionEvent);
}
/* This helper function helps with the form_complete pageTypes so the correct interaction name
 * is fired based on the form completed.
*/
function handleCompleteInteraction() {
    if (/^\/account\-application\-complete$/.test(window.location.pathname)) {
        return "Open an Account Form - Complete";
    } else if (/^\/quote\-application\-complete$/.test(window.location.pathname)) {
        return "Get A Quote Form - Complete";
    } else if (/loan\-application\-complete/.test(window.location.pathname)) {
        return "Pre-Approved Form - Complete";
    } else {
        return "Schedule Apppointment Form - Complete";
    }
}

SalesforceInteractions.init({
    cookieDomain: "cumulusfinserv.com",
    consents: [{
        purpose: SalesforceInteractions.mcis.ConsentPurpose.Personalization,
        provider: "Example Consent Manager",
        status: SalesforceInteractions.ConsentStatus.OptIn
    }]
}).then(() => {
    const sitemapConfig = {
        global: {
            contentZones: [
                { name: "global_popup"}
            ]
        },
        pageTypeDefault: {
            name: "default"
        },
        pageTypes: [
            {
                name: "personal_home",
                isMatch: () => /^\/$/.test(window.location.pathname),
                interaction: {
                    name: "Personal - Homepage"
                },
                contentZones: [
                    { name: "personal_home_hero", selector: ".hero-inner" },
                    { name: "personal_home_recommendations", selector: ".intro-content" },
                    { name: "personal_home_nav", selector: "body > div.category-menu" },
                ]
            },
            {
                name: "corporate_home",
                isMatch: () => /^\/corporate$/.test(window.location.pathname),
                interaction: {
                    name: "Corporate - Homepage"
                },
                contentZones: [
                    { name: "corporate_home_hero", selector: ".hero-inner" },
                    { name: "corporate_home_recommendations", selector: ".intro-content" },
                    { name: "corporate_home_nav", selector: "body > div.category-menu" },
                ]
            },
            {
                name: "login",
                isMatch: () => /^\/login$/.test(window.location.pathname),
                interaction: {
                    name: "Login Page"
                },
                listeners: [
                    SalesforceInteractions.listener("submit", ".form-signin", () => {
                        handleFormInteraction({
                            user: {
                                identities: {
                                    emailAddress: SalesforceInteractions.cashDom("inputEmail").val(),
                                    }
                                },
                            interactionName: "Contact Form Submit"
                        });
                    })
                ]
            },
            {
                name: "contact_us",
                isMatch: () => /^\/company\/contact\-us$/.test(window.location.pathname),
                interaction: {
                    name: "Contact Us"
                },
                listeners: [
                    SalesforceInteractions.listener("submit", ".form-signin", () => {
                        handleFormInteraction({
                            user: {
                                attributes: {
                                    message: SalesforceInteractions.cashDom(".form-control.contact").val()
                                }
                            },
                            interactionName: "Contact Form Submit"
                        });

                    })
                ]
            },
            {
                name: "pdp",
                isMatch: () => SalesforceInteractions.cashDom("div.container.product-intro").length > 0,
                interaction: {
                    name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
                    catalogObject: {
                        type: "Product",
                        id: SalesforceInteractions.resolvers.fromHref((url) => url.split("/").splice(-1)[0].toUpperCase()),
                        attributes: {
                            name: SalesforceInteractions.resolvers.fromSelector("h1"),
                            description: SalesforceInteractions.resolvers.fromSelector(".product-intro h3"),
                            price: 1,
                            url: SalesforceInteractions.resolvers.fromHref(),
                            imageUrl: SalesforceInteractions.resolvers.fromSelectorAttribute(".img-responsive", "src"),
                            inventoryCount: 1
                        },
                        relatedCatalogObjects: {
                            Category: SalesforceInteractions.resolvers.buildCategoryId(".nav a.current span", null, null, (id) => {
                                let topLevel = SalesforceInteractions.cashDom("li.current a").text().trim().toUpperCase();
                                return [topLevel+"|"+id.toUpperCase()];
                            }),
                            ItemClass: SalesforceInteractions.resolvers.fromSelectorMultiple("li.current a"),
                            Keyword: SalesforceInteractions.resolvers.fromMeta("keywords", (keyword) => {
                                return [keyword];
                            }),
                            Benefits: SalesforceInteractions.resolvers.fromSelectorMultiple(".product-details .col-md-6:nth-of-type(1) li"),
                            Requirements: SalesforceInteractions.resolvers.fromSelectorMultiple(".product-details .col-md-6:nth-of-type(2) li")
                        }
                    }
                },
                listeners: [
                    SalesforceInteractions.listener("click", ".product-intro .btn.green-btn.btn-med", handleAddToCart)
                ],
                contentZones: [
                    { name: "pdp_cta", selector: ".btn.green-btn.btn-med" },
                    { name: "pdp_image", selector: ".pdp-img-responsive"}
                ]
            },
            {
                name: "Category",
                isMatch: () => SalesforceInteractions.cashDom("div.offerings").length === 1,
                interaction: {
                    name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
                    catalogObject: {
                        type: "Category",
                        id: SalesforceInteractions.resolvers.buildCategoryId(".nav a.current span", null, null, (id) => {
                            let topLevel = SalesforceInteractions.cashDom("li.current a").text().trim().toUpperCase();
                            if (/.*\/investing\/retirement\-planning$/.test(window.location.href)) {
                                return "PERSONAL|INVESTING|RETIREMENT PLANNING";
                            } else {
                                return topLevel+"|"+id.toUpperCase();
                            }
                        }),
                        attributes: {
                            name: SalesforceInteractions.resolvers.fromSelector("h1"),
                            url: SalesforceInteractions.resolvers.fromHref(),
                            imageUrl: SalesforceInteractions.resolvers.fromSelectorAttribute(".img-responsive", "src"),
                        }
                    }
                },
                contentZones: [
                    { name: "category_hero_img", selector: ".svg-hero-container img" }
                ]
            },
            {
                name: "pre_approved",
                isMatch: () => /\/get-preapproved/.test(window.location.href),
                interaction: {
                    name: "Pre-Approved"
                },
                listeners: [
                    SalesforceInteractions.listener("click", "#form-application-01-next", () => {
                        handleFormInteraction({
                            interactionName: "Pre-Approved Form - Step 1 Submit",
                        });
                    }),
                     SalesforceInteractions.listener("click", "#form-application-02-next", () => {
                        handleFormInteraction({
                            user: {
                                attributes: {
                                    loanAmount: SalesforceInteractions.cashDom("#form-application-loan-amount").val(),
                                    purchasePrice: SalesforceInteractions.cashDom("#form-application-purchase-price").val(),
                                    downPayment: SalesforceInteractions.cashDom("#form-application-down-payment").val(),
                                    propertyType: SalesforceInteractions.cashDom("#form-application-property-type").val(),
                                    realtorPhone: SalesforceInteractions.cashDom("#form-application-phone-number").val()
                                }
                            },
                            interactionName: "Pre-Approved Form - Step 2 Submit",
                        });
                    }),
                    SalesforceInteractions.listener("click", "#startJourney", () => {
                        handleFormInteraction({
                            interactionName: SalesforceInteractions.OrderInteractionName.Purchase,
                            user: {
                                attributes: {
                                    income: SalesforceInteractions.cashDom("input[name='income']").val(),
                                    assets: SalesforceInteractions.cashDom("input[name='assets']").val()
                                }
                            },
                            order: {
                                lineItems: handleLineItems()
                            }
                        })
                    }),
                    SalesforceInteractions.listener("click", "#msform", (event) => {
                        if (SalesforceInteractions.cashDom(event.target).closest(".save").length > 0) {
                            const step = SalesforceInteractions.cashDom("#progressbar .active").length;
                            if (step > 0) {
                                handleFormInteraction({
                                    user: {
                                        attributes: { accountLifecycleState: "Pre-approved Open" }
                                    },
                                    interactionName: "Pre-approved Form Step " + step + " Save For Later",
                                });
                            }
                        }
                    })
                ]
            },
            {
                name: "form_complete",
                isMatch: () => /(appointment\-confirmed)|(loan\-application\-complete)|(^\/quote\-application\-complete$)
                |(^\/account\-application\-complete$)]/.test(window.location.pathname),
                interaction: {
                    name: handleCompleteInteraction()
                },
                contentZones: [
                    { name: "form_complete_app_wrapper", selector: ".application-wrapper" },
                    { name: "schedule_appointment_complete_app_wrapper", selector: ".ty-white-wrapper" }
                ]
            },
            {
                name: "get_quote",
                isMatch: () => /\/get\-a\-quote/.test(window.location.href),
                interaction: {
                    name: "Get A Quote"
                },
                listeners: [
                    SalesforceInteractions.listener("click", "#form-application-01-next", () => {
                        handleFormInteraction({
                            interactionName: "Get A Quote Form - Step 1 Submit",
                        });
                    }),
                     SalesforceInteractions.listener("click", "#form-application-02-next", () => {
                        handleFormInteraction({
                            user: {
                                attributes: {
                                    lastInsuranceType: SalesforceInteractions.cashDom("#insuranceType").val().toUpperCase(),
                                }
                            },
                            interactionName: "Get A Quote Form - Step 2 Submit",
                        });
                    }),
                    SalesforceInteractions.listener("click", "#startJourney", () => {
                        handleFormInteraction({
                            interactionName: SalesforceInteractions.OrderInteractionName.Purchase,
                            order: {
                                lineItems: handleLineItems()
                            }
                        })
                    }),
                    SalesforceInteractions.listener("click", "#msform", (event) => {
                        if (SalesforceInteractions.cashDom(event.target).closest(".save").length > 0) {
                            const step = SalesforceInteractions.cashDom("#progressbar .active").length;
                            if (step > 0) {
                                handleFormInteraction({
                                    user: {
                                        attributes: { accountLifecycleState: "Get A Quote Open" }
                                    },
                                    interactionName: "Get a Quote Form Step " + step + " Save For Later",
                                });
                            }
                        }
                    })
                ]
            },
            {
                name: "apply_creditcard",
                isMatch: () => /\/apply\-for\-a\-card/.test(window.location.href),
                interaction: {
                    name: "Apply For Credit Card"
                },
                listeners: [
                    SalesforceInteractions.listener("click", "fieldset:nth-of-type(1) input.next.btn.green-btn.btn-med", (event) => {
                        handleFormInteraction({
                            interactionName: "Apply for Credit Card Form - Step 1 Submit",
                        });
                    }),
                     SalesforceInteractions.listener("click", "fieldset:nth-of-type(2) input.next.btn.green-btn.btn-med", (event) => {
                        handleFormInteraction({
                            user: {
                                attributes: {
                                    lastCCType: SalesforceInteractions.cashDom("#card option").val().toUpperCase(),
                                }
                            },
                            interactionName: "Apply for Credit Card Form - Step 2 Submit",
                        });
                    }),
                    SalesforceInteractions.listener("click", "fieldset:nth-of-type(3) input.next.btn.green-btn.btn-med", (event) => {
                        handleFormInteraction({
                            user: {
                                attributes: {
                                    city: SalesforceInteractions.cashDom("input[name='city']").val(),
                                    state: SalesforceInteractions.cashDom("input[name='state']").val()
                                }
                            },
                            interactionName: "Apply for Credit Card Form - Step 3 Submit",
                        });
                    }),
                    SalesforceInteractions.listener("click", "#startJourney", () => {
                        handleFormInteraction({
                            interactionName: SalesforceInteractions.OrderInteractionName.Purchase,
                            order: {
                                lineItems: handleLineItems()
                            }
                        })
                    }),
                    SalesforceInteractions.listener("click", "#msform", (event) => {
                        if (SalesforceInteractions.cashDom(event.target).closest(".save").length > 0) {
                            const step = SalesforceInteractions.cashDom("#progressbar .active").length;
                            if (step > 0) {
                                handleFormInteraction({
                                    user: {
                                        attributes: { accountLifecycleState: "Apply for Credit Card Open" }
                                    },
                                    interactionName: "Apply for Credit Card Form Step " + step + " Save For Later",
                                });
                            }
                        }
                    })
                ]
            },
            {
                name: "open_account",
                isMatch: () => /\/open\-an\-account/.test(window.location.href),
                interaction: {
                    name: "Open an Account"
                },
                listeners: [
                    SalesforceInteractions.listener("click", "#form-application-01-next", () => {
                        handleFormInteraction({
                            interactionName: "Open an Account Form - Step 1 Submit",
                        });
                    }),
                     SalesforceInteractions.listener("click", "#form-application-02-next", (event) => {
                        handleFormInteraction({
                            user: {
                                attributes: {
                                    lastAccountType: SalesforceInteractions.cashDom("#form-application-account-type").val().toUpperCase(),
                                }
                            },
                            interactionName: "Open an Account Form - Step 2 Submit",
                        });
                    }),
                    SalesforceInteractions.listener("click", "#form-application-03-next", () => {
                        handleFormInteraction({
                            user: {
                                attributes: {
                                    addressLine2: SalesforceInteractions.cashDom("#form-application-address-02").val(),
                                    city: SalesforceInteractions.cashDom("#form-application-city").val(),
                                    state: SalesforceInteractions.cashDom("#form-application-state").val(),
                                }
                            },
                            interactionName: "Open an Account Form - Step 3 Submit",
                        });
                    }),
                    SalesforceInteractions.listener("click", "#startJourney", () => {
                        handleFormInteraction({
                            interactionName: SalesforceInteractions.OrderInteractionName.Purchase,
                            order: {
                                lineItems: handleLineItems()
                            }
                        })
                    }),
                    SalesforceInteractions.listener("click", "#msform", (event) => {
                        if (SalesforceInteractions.cashDom(event.target).closest(".save").length > 0) {
                            const step = SalesforceInteractions.cashDom("#progressbar .active").length;
                            if (step > 0) {
                                handleFormInteraction({
                                    user: {
                                        attributes: { accountLifecycleState: "Account Application Open" }
                                    },
                                    interactionName: "Open an Account Form Step " + step + " Save For Later",
                                });
                            }
                        }
                    })
                ]
            },
            {
                name: "schedule_appointment",
                isMatch: () => /\/corporate\/schedule\-appointment$/.test(window.location.href),
                interaction: {
                    name: "Schedule Appointment"
                },
                listeners: [
                    SalesforceInteractions.listener("click", "#form-appointment-schedule-btn", () => {
                        handleFormInteraction({
                            interactionName: SalesforceInteractions.OrderInteractionName.Purchase,
                            order: {
                                lineItems: handleLineItems()
                            },
                            user: {
                                attributes: {
                                    appointmentReason: SalesforceInteractions.cashDom("#form-appointment-reason").val(),
                                    branch: SalesforceInteractions.cashDom("#form-appointment-branch").val(),
                                    lastApptDate: SalesforceInteractions.cashDom("#form-appointment-date").val(),
                                    lastApptTime: SalesforceInteractions.cashDom("#form-appointment-time").val()
                                }
                            }
                        })
                    })
                ]
            },
            {
                name: "learn_more",
                isMatch: () => /\/corporate\/learn\-more/.test(window.location.href),
                interaction: {
                    name: "Learn More"
                },
                listeners: [
                    SalesforceInteractions.listener("click", "#form-advisor-submit-btn", () => {
                        handleFormInteraction({
                            interactionName: "Learn More Form - Submit",
                            user: {
                                attributes: {
                                    companySize: SalesforceInteractions.cashDom("#form-advisor-company-size").val(),
                                    industry: SalesforceInteractions.cashDom("#form-advisor-industry").val(),
                                }
                            }
                        })
                    })
                ]
            }
        ]
    };

    SalesforceInteractions.initSitemap(sitemapConfig);
});
```

## Example Sitemap for the Evergage Namespace

```javascript
Evergage.init().then(() => {
  const config = {
    global: {},
    pageTypes: [
      {
        name: "home",
        action: "Homepage",
        isMatch: () => /^\/$/.test(window.location.pathname),
        contentZones: [
          { name: "home_hero", selector: ".hero-inner" },
          { name: "home_recommendations", selector: ".intro-content" },
          { name: "home_nav", selector: "body > div.category-menu" },
        ],
      },
      {
        name: "product_detail",
        isMatch: () => Evergage.cashDom("div.container.product-intro").length > 0,
        action: "View Product",
        catalog: {
          Product: {
            _id: Evergage.resolvers.fromHref((url) => url.split("/").splice(-1)[0].toUpperCase()),
            name: Evergage.resolvers.fromSelector("h1"),
            price: 1,
            url: Evergage.resolvers.fromHref(),
            imageUrl: Evergage.resolvers.fromSelectorAttribute(".img-responsive", "src"),
            inventoryCount: 1,
            categories: Evergage.resolvers.buildCategoryId(
              ".nav a.current span",
              null,
              null,
              (id) => {
                return [id];
              },
            ),
            relatedCatalogObjects: {
              // In case you're using 'dimensions' instead of 'relatedCatalogObjects', you can continue to do so as they both function the same way.
              ItemClass: Evergage.resolvers.fromSelectorMultiple("li.current a"),
            },
          },
        },
        listeners: [
          Evergage.listener("click", ".product-intro .btn.green-btn.btn-med", (event) => {
            Evergage.sendEvent({
              itemAction: Evergage.ItemAction.AddToCart,
              cart: {
                singleLine: {
                  Product: {
                    _id: Evergage.util
                      .getPathname(window.location.href)
                      .split("/")
                      .splice(-1)[0]
                      .toUpperCase(),
                    price: 1,
                    quantity: 1,
                  },
                },
              },
            });
          }),
        ],
        contentZones: [{ name: "product_detail_cta", selector: ".btn.green-btn.btn-med" }],
      },
      {
        name: "pre_approved",
        isMatch: () => /\/get-preapproved/.test(window.location.href),
        action: "Pre-Approved",
        listeners: [
          Evergage.listener("click", "#msform", (event) => {
            if (Evergage.cashDom(event.target).closest(".next").length > 0) {
              const step = Evergage.cashDom("#progressbar .active").length - 1;
              if (step > 0) {
                const email = Evergage.cashDom("#form-application-email").val();
                let actionEvent = {
                  user: {},
                  action: "Get Pre-Approved Form Step " + step + " Submit",
                };
                if (email) {
                  actionEvent.user.id = email;
                }
                Evergage.sendEvent(actionEvent);
              }
            } else if (Evergage.cashDom(event.target).closest(".save").length > 0) {
              const step = Evergage.cashDom("#progressbar .active").length;
              if (step > 0) {
                const email = Evergage.cashDom("#form-application-email").val();
                let actionEvent = {
                  user: {
                    attributes: { LifecycleState: "Mortgage Application Open" },
                  },
                  action: "Get Pre-Approved Form Step " + step + " Save For Later",
                };
                if (email) {
                  actionEvent.user.id = email;
                }
                Evergage.sendEvent(actionEvent);
              }
            }
          }),
        ],
      },
    ],
  };

  Evergage.initSitemap(config);
});
```

<!-- document id=f9305ca5fecf0f96448d517a63849352b6753627bd0caccccdedb1f95eb30be0 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/web-campaigns-templates/flicker-defender.md -->

# Flicker Defender

The Flicker Defender gear can help prevent flicker caused by the rendering of personalized content (Templates/Campaigns) served by the Marketing Cloud Personalization platform.

Flicker Defender helps prevent flicker by doing the following.

- Initially hides every content zone that has a `selector` by temporarily applying the `visibility: hidden !important` style to elements targeted by that `selector`
- Each hidden content zone is then redisplayed depending on:
  - If it is not targeted by a Template/Campaign for which the user has qualified
  - Upon resolution of the Template/Campaign targeting it
  - When the `redisplayTimeout` is hit
- If a page is not matched or if the Sitemap errors, all hidden content zones are redisplayed following the `pageMatchTimeout`

While there is no limit for either of the timeout values, it is advised to stay under 10000 ms (10 seconds). Additionally, ensure that `pageMatchTimeout` is less than or equal to the `redisplayTimeout`, since `redisplayTimeout` ultimately decides when to reshow all hidden content.

---

## Requirements

For Flicker Defender to work correctly, ensure you meet the following requirements.

- A synchronously integrated Beacon in the `head` of the site is a strict requirement for Flicker Defender to work correctly.
- A working sitemap is necessary for Flicker Defender to work correctly and efficiently. For information on writing a Sitemap, see the [Web Integration](https://developer.salesforce.com/docs/marketing/web-integration.md) documentation.
- At least one Content Zone with a `selector` attribute. _(Note that it is the developer's responsibility to ensure that the CSS selector used is valid.)_

---

## Timeout Configuration

The following Flicker Defense timeout options are configurable from within Site-Wide JavaScript.

```typescript
setPageMatchTimeout(pageMatchTimeout: number = 1000): void
```

`pageMatchTimeout` controls the maximum length of time to wait for a page to be successfully matched before reshowing all hidden content

```javascript
// Example:
SalesforceInteractions.mcis.FlickerDefender.setPageMatchTimeout(2500);
```

```javascript
// Example:
Evergage.FlickerDefender.setPageMatchTimeout(2500);
```

`redisplayTimeout` controls the maximum length of time that content should ever be hidden.

```typescript
setRedisplayTimeout(redisplayTimeout: number = 2500): void
```

```javascript
// Example:
SalesforceInteractions.mcis.FlickerDefender.setRedisplayTimeout(5000);
```

```javascript
// Example:
Evergage.FlickerDefender.setRedisplayTimeout(5000);
```

**note:** Depending on the namespace you're using, calls to `setPageMatchTimeout` and/or `setRedisplayTimeout` must be done before the call to either `SalesforceInteractions.init()` or `Evergage.init()` in Site-Wide JavaScript.

```javascript
// Example:
if (
  typeof (SalesforceInteractions.mcis.FlickerDefender || {}).setPageMatchTimeout === "function"
) {
  SalesforceInteractions.mcis.FlickerDefender.setPageMatchTimeout(2500);
}

if (
  typeof (SalesforceInteractions.mcis.FlickerDefender || {}).setRedisplayTimeout === "function"
) {
  SalesforceInteractions.mcis.FlickerDefender.setRedisplayTimeout(5000);
}

SalesforceInteractions.init().then(() => {
  // sitemap
});
```

```javascript
// Example:
if (typeof (Evergage.FlickerDefender || {}).setPageMatchTimeout === "function") {
  Evergage.FlickerDefender.setPageMatchTimeout(2500);
}

if (typeof (Evergage.FlickerDefender || {}).setRedisplayTimeout === "function") {
  Evergage.FlickerDefender.setRedisplayTimeout(5000);
}

Evergage.init().then(() => {
  // sitemap
});
```

**important:** - By design, Flicker Defender does not run in the Template or Campaign Editors.
- Depending on the SDK namespace you're using, ensure that you call `SalesforceInteractions.init` and `SalesforceInteractions.initSitemap` or `Evergage.init` and `Evergage.initSitemap` as soon as possible in Site-Wide JavaScript, since Flicker Defender relies on those calls to determine when to begin hiding content zones.
- When injecting or forcing the Web SDK URL using the Salesforce Interactions SDK Launcher browser extension, you are simulating an asynchronous implementation of the product. Therefore, at least a small amount of Flicker always appears when injecting or forcing a Web SDK onto the page.

## Disabling Flicker Defender

To effectively disable the Flicker Defender gear, add the following to the top of your sitewide JavaScript.

```javascript
if (
  typeof (SalesforceInteractions.mcis.FlickerDefender || {}).setPageMatchTimeout === "function"
) {
  SalesforceInteractions.mcis.FlickerDefender.setPageMatchTimeout(0);
}

if (
  typeof (SalesforceInteractions.mcis.FlickerDefender || {}).setRedisplayTimeout === "function"
) {
  SalesforceInteractions.mcis.FlickerDefender.setRedisplayTimeout(0);
}
```

```javascript
if (typeof (Evergage.FlickerDefender || {}).setPageMatchTimeout === "function") {
  Evergage.FlickerDefender.setPageMatchTimeout(0);
}

if (typeof (Evergage.FlickerDefender || {}).setRedisplayTimeout === "function") {
  Evergage.FlickerDefender.setRedisplayTimeout(0);
}
```

<!-- document id=fde0dc88a0321a7a9a1538c22eec69db90aae10831150e18e0c16e642c2d0fff url=/developer/current/en-us/personalization/personalization/guides/campaign-development/templates/get-started-global-web-templates.md -->

# Get Started with Global Web Templates

The simplest way to develop a Marketing Cloud Personalization web template is to use one of our global templates and customize it for your business use case. To use a global template, do the following.

1. Clone the global template that most closely represents your web channel use case.
2. Customize the template based on business user requirements.

The following sections present the steps for cloning a global template in Personalization and the standards for customizing global template code.

For information on the most current list of available global templates and their recommended web channel use cases, see [Web Campaign Template Properties](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_template_properties.htm) on Salesforce Help.

## Clone a Global Template

To clone a global template, do the following:

1. Open the [Salesforce Interactions SDK Launcher](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_interactions_sdk_launcher.htm) Chrome extension tool, and click the **View List** section of the template button:

   ![Launcher View Template List](https://developer.salesforce.com/media/campaign-development/launcher-view-list.png)

2. To find a list of all currently available global templates, click the **Global Templates** tab.
3. To clone a global template for customization, click the **Clone Global Template** button associated with the global template you want to customize.

   ![Global Templates](https://developer.salesforce.com/media/campaign-development/global-templates.png)

4. Cloning a global template opens a new copy of the template, with the text "[CLONE]" prepended to the template name.

   **note:** Cloning and customizing a global template doesn’t alter the original version of the global template in the **Global Templates** tab. You can make as many clones of a global template as you require for different use cases.

   ![Clone Global Template](https://developer.salesforce.com/media/campaign-development/global-templates-clone.png)

   **note:** In global templates, comments are provided at the top of the code tabs to help template developers effectively customize the template. For an example of comments within global templates, see the comments in the **Handlebars** tab in the above **[CLONE] Einstein Product Recommendations** figure.

5. Click **Save** to save the cloned version of the global template to your dataset. This cloned version appears in the **Templates** tab along with any other templates you’ve created or cloned.

   ![Template List](https://developer.salesforce.com/media/campaign-development/templates-list-with-cloned-global-template.png)

## Customize the Template

After you’ve cloned a global template as described in the preceding section, customize the template components to meet the requirements of the business use case. As a best practice, we recommend you modify the template component code in the following order:

1. Modify the server-side code in the **Serverside Code** tab. See [Web Template Server TypeScript](https://developer.salesforce.com/docs/marketing/personalization/guide/template-server-typescript.md) for more detail.
2. Modify the client-side code in the **Clientside Code** tab. See [Web Template Client JavaScript](https://developer.salesforce.com/docs/marketing/personalization/guide/template-client-javascript.md) for more detail.
3. Develop the Handlebars templated HTML code in the **Handlebars** tab. See [Web Template Handlebars](https://developer.salesforce.com/docs/marketing/personalization/guide/web-template-handlebars.md) for more detail.
4. Develop the CSS style code in the **CSS** tab. See [Web Template CSS](https://developer.salesforce.com/docs/marketing/personalization/guide/web-template-css.md) for more detail.

## Template Developer Best Practices

When customizing global templates, follow the recommendations outlined in the following articles.

- [Web Template Building Best Practices](https://developer.salesforce.com/docs/marketing/personalization/web-campaigns-templates/web-template-building-best-practices.md) provide an outline of standards for building templates that run optimally on your website.
- [Web Templates Style Guide and Coding Conventions](https://developer.salesforce.com/docs/marketing/personalization/web-campaigns-templates/web-templates-style-guide-and-coding-conventions.md) provide a guide to writing consistent template code.

## See Also

- _Salesforce Help_: [Web Campaign Template Properties](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_template_properties.htm)
- _Salesforce Help_: [Install the Salesforce Interactions SDK Launcher](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_interactions_sdk_launcher.htm)

<!-- document id=1e43c70199f8cd0d18187d212574f55b35264c188859465050fea6c73a2bbe5f url=/developer/current/en-us/personalization/personalization/guides/get-started.md -->

# Get Started with Marketing Cloud Personalization

You can configure Personalization to support customer engagement campaigns across many different digital communication channels, including Web, Email, and Mobile. It also supports campaigns through integrations with other systems such as CRM and other external data systems.

You can perform some of these tasks in the Personalization UI, while other require writing code specific to the requirements of the company and its business users.

Developer tasks refer to those tasks that require some kind of code development, while business user tasks refer to tasks carried out by users in the Personalization UI.

This documentation explains the tasks for developers.

To learn how businesses use channels and develop campaigns in the Personalization UI, see [Channels and Campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_channel_campaign.htm) on Salesforce Help.

## Integrate Web Sites

[Web channel campaigns](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-development.md) and the [web templates](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-development/personalization-template-system.md) that support them require integration with the company website. This integration is achieved through the Salesforce Interactions SDK and the [Sitemap](https://developer.salesforce.com/docs/marketing/personalization/guide/web-integration/personalization-sitemap.md), a part of the Web SDK, that recognizes, processes and sends user interactivity data from the website to Personalization. The individual or team responsible for managing scripts on the company website must deploy the Salesforce Interactions SDK to the designated company website pages. Then, a developer must validate the deployment and configure the Sitemap based on the data processing requirements provided by the business. The articles in the [Web Integration](https://developer.salesforce.com/docs/marketing/personalization/guide/web-integration.md) section of this site provide website integration planning considerations, Salesforce Interactions SDK specifications, and Sitemap configuration requirements.

## Develop Web Templates

Before business users can develop web campaigns in the Personalization UI, Personalization developers must create the framework for displaying those web campaigns by developing reusable web templates.

The [Campaign Development](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-development.md) section of this site explains the web campaign development process from the developer perspective and contains the articles explaining the technical requirements for web template development.

## Integrate Real-Time Event Data

Use the [Event API](https://developer.salesforce.com/docs/marketing/personalization/guide/event-api/event-api.md) to process real-time data. The Event API is a REST API that processes and responds to event data sent from the Sitemap or from external systems.

The articles in the [Event API](https://developer.salesforce.com/docs/marketing/personalization/guide/event-api/event-api.md) section of this site cover the purpose, capabilities and requirements for using the Event API, HTTP request and response specifications, and HTTP request and response examples for common Personalization use cases.

## Integrate Data Ingestion Systems

Personalization supports batch data ingestion and processing from external data system sources through ETL or other batch data processing technologies. The complete requirements for integrating external data systems for batch data ingestion into Personalization are documented in the [About ETL Data Feeds](https://help.salesforce.com/s/articleView?id=sf.mc_pers_etl_integration_about.htm) article on Salesforce Help. See [Data Ingestion](https://developer.salesforce.com/docs/marketing/personalization/guide/data-ingestion.md) in this developer site for a brief overview.

## Integrate Mobile Apps and Responsive Templates

Personalization can support campaigns for display on mobile devices by using responsive HTML (HTML5) in its normal [web templates](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-development/personalization-template-system.md) feature or through integration with native iOS and Android mobile apps.

See [Personalization Mobile Integrations](https://developer.salesforce.com/docs/marketing/personalization/guide/mobile-integration.md) for an introduction to the capabilities of the Personalization iOS and Android mobile app integrations and links to the separate native mobile app developer documentation websites.

## See Also

- [_Salesforce Help_: Channels and Campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_channel_campaign.htm)
- [_Salesforce Help_: About ETL Data Feeds](https://help.salesforce.com/s/articleView?id=sf.mc_pers_etl_integration_about.htm)

<!-- document id=3be20fa5209ede1f0b55970c1c35b243665186adc97dbfb735274cb80dcebf2b url=/developer/current/en-us/personalization/personalization/guides/web-integration/sitemapping-getting-started.md -->

# Get Started with Site Mapping

A Marketing Cloud Personalization Sitemap is a configuration-driven system deployed by and executed within the Personalization module of the Salesforce Interactions SDK. The Sitemap configuration data enables other parts of the Personalization platform to register and receive events from the client context. This article provides guidance for configuring the JavaScript components of a Sitemap required to implement the Personalization web channel solution architecture. For a more comprehensive introduction to the Sitemap, see [Sitemap Overview](https://developer.salesforce.com/docs/marketing/personalization/guide/personalization-sitemap.md).

## Sitemap Development Process

To develop a Sitemap, do the following.

1. Navigate to the site that contains the Personalization JavaScript Web SDK.
2. Launch the Personalization **Visual Editor** and log in. For guidance on installing and starting the Personalization Visual Editor, refer to the [Install the Salesforce Interactions SDK Launcher](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_interactions_sdk_launcher.htm).
   ![Launch Salesforce Interactions SDK Launcher](https://developer.salesforce.com/media/Interaction-Studio-Launcher.png)
3. Open the Sitemap Editor by clicking **Site Map**, as highlighted in the following image.
   ![Launch the Site Map](https://developer.salesforce.com/media/site-map-launch.png)
4. In the **Sitemap JS** tab of the Sitemap Editor, configure the JavaScript components required for your Sitemap as described in the remaining sections of this article.
   ![Sitemap Editor](https://developer.salesforce.com/media/sitemap-editor.png)

## Sitemap JavaScript Configuration Overview

A Sitemap is built and initialized after the Personalization Web SDK is initialized. Developing a Sitemap consists of writing the JavaScript required to do the following.

1. Initializing the Web SDK
2. Configuring the Sitemap JavaScript objects
3. Initializing the Sitemap

### Sitemap JavaScript Code Structure

The following code samples depict the general JavaScript code structure for a Sitemap in each of the SDK namespaces.

```javascript
SalesforceInteractions.init({
  // Initializes the Personalization module of the Salesforce Interactions SDK
  cookieDomain: "company.com", // Optional tracking cookie domain configuration (overrides default)
}).then(() => {
  const sitemapConfig = {
    // Sitemap configuration object
    global: {}, // Object used to contain Global site object configuration
    pageTypes: [], // Array used to contain the page type object configurations
  };

  SalesforceInteractions.initSitemap(sitemapConfig); // Initializes the Sitemap
});
```

```javascript
Evergage.init({
  // Initializes the Personalization module of the Salesforce Interactions SDK
  cookieDomain: "company.com", // Optional tracking cookie domain configuration (overrides default)
}).then(() => {
  const sitemapConfig = {
    // Sitemap configuration object
    global: {}, // Object used to contain Global site object configuration
    pageTypes: [], // Array used to contain the page type object configurations
  };

  Evergage.initSitemap(sitemapConfig); // Initializes the Sitemap
});
```

The following sections present the considerations and guidance for developing each functional component of a Sitemap. For examples of complete Sitemap configurations, see [Example Sitemaps](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps.md).

## Initialize the Personalization module of the Salesforce Interactions SDK

At the beginning of the Sitemap JavaScript, you must initialize the Personalization module of the Salesforce Interactions SDK with the following function.

```javascript
SalesforceInteractions.init({

}).then(() => { }

---Sitemap Configuration---
```

```javascript
Evergage.init({

}).then(() => { }

---Sitemap Configuration---
```

The preceding function initializes the Personalization module of the Web SDK and allows it to begin tracking. The Web SDK starts tracking only if `SalesforceInteractions.init()` is called.

### Specify an Optional Configuration of the Web SDK

You can specify an optional configuration of the Web SDK by setting `config` object parameters for the `SalesforceInteractions.init` function. These parameters are strictly optional and aren’t required for the Sitemap to function correctly.

The following table lists the optional parameters accepted by the `config` object.

| Field Name     | Expected Value Type | Required? | Description                                                                                                                                                                                                                                                                                                                                                            |
| -------------- | ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trackerUrl`   | String              | No        | Overrides the default URL where the tracker sends events. The `trackerUrl` is of the format `https://<accountName>.<instance>.evergage.com`, where `accountName` is your Personalization account name and `instance` is your Personalization instance identifier. You can retrieve these details by accessing Gears from the Personalization UI and reviewing the URL. |
| `dataset`      | String              | No        | Name or identifier of your Personalization dataset                                                                                                                                                                                                                                                                                                                     |
| `cookieDomain` | String              | No        | Overrides the default domain used for setting the Personalization tracking cookie                                                                                                                                                                                                                                                                                      |

**important:** Ensure that you use the `account`, `dataset`, and `trackerUrl` parameters exclusively in your staging environment for testing purposes and seldom in your production environment. You can use these parameters to configure Sitemap operations to occur in your sandbox or learning environment without disrupting your production environment. Although there are instances where you have to use the `trackerUrl` parameter in your production environment, such instances are incredibly rare.

You can use the `cookieDomain` parameter in the production environment in scenarios where you must share the tracking cookie across all possible subdomains of the default site host. For example, if the default site host is `something.company.com`, the tracking cookie is set only on that host by default. You can override this domain to share the cookie across all subdomains of `company.com` with the following configuration.

```javascript
SalesforceInteractions.init({
  cookieDomain: "company.com",
});
```

```javascript
Evergage.init({
  cookieDomain: "company.com",
});
```

#### Optional Web SDK `config` Parameter Example

The following code samples depict an optional configuration of the Web SDK using `config` object parameters.

```javascript
SalesforceInteractions.init({
  trackerUrl: "https://<accountName>.<instance>.evergage.com",
  cookieDomain: "staging.company.com",
});
```

```javascript
Evergage.init({
  trackerUrl: "https://<accountName>.<instance>.evergage.com",
  cookieDomain: "staging.company.com",
});
```

**note:** As mentioned in the previous section, use the `trackerUrl` parameter only in your staging or learning environment and never in your production environment. However, you can use the `cookieDomain` parameter in your production or staging environment as needed.

## Configure Sitemap Objects

The `const sitemapConfig` variable is used to configure the JavaScript objects that capture site visitor actions. You can use the optional `global` object to define the user actions to be captured on every page that is matched as a page type. The pageTypes array is used to contain the configurations of one or more specific page types in a site. A Sitemap developer must configure one `global` object, and the `pageTypes` array must have a page type object configured for each page type on the site.

### Common Object Configuration Examples

A Sitemap can accept any valid JavaScript. Some JavaScript objects from the Personalization Web SDK are required to support the Personalization data collection and transmission functionality. Some are required in the `pageTypes` array configuration but not used in the `global` object.

The following table describes the JavaScript objects from the Web SDK commonly used in the Sitemap `global` and `pageTypes` configurations.

| Object          | Purpose                                                                                                                              | Usage             | Configuration                         | Namespace                |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ------------------------------------- | ------------------------ |
| `contentZones`  | The array of objects used to indicate areas of a page that are eligible for customization                                            | Optional          | Global object or configured page type | Both                     |
| `listeners`     | The array of `listener()` functions used to listen for user actions that trigger events to send to Personalization                   | Optional          | Global object or configured page type | Both                     |
| `isMatch`       | The function required (along with the page name) to match a specific page type                                                       | **Required**      | Configured page type only             | Both                     |
| `catalog`       | The object used to collect and send data on catalog items. Used only with the `Evergage` namespace.                                  | Optional          | Configured page type only             | `Evergage`               |
| `order`         | The object used to collect and send order data to Personalization, including line items, order IDs, total order value, and currency. | Context-dependent | Configured page type only             | `Evergage`               |
| `action`        | The property of `ActionEvent` that is used to identify user actions sent to Personalization                                          | Context-dependent | Global object or configured page type | `Evergage`               |
| `itemAction`    | The property of `ActionEvent` used to identify user actions taken on catalog items such as "Purchase" or "AddToCart".                | Context-dependent | Configured page type only             | `Evergage`               |
| `interaction`   | The property of `ActionEvent` used to identify user actions taken on catalog items such as "Purchase" or "AddToCart".                | Context-dependent | Configured page type only             | `SalesforceInteractions` |
| `onActionEvent` | The function used with `ActionEvent` that sends events to Personalization based on user actions                                      | Optional          | Global object or configured page type | Both                     |

**important:** If you're using the `Evergage` namespace within your Sitemap code, you must continue to use the `itemAction` property instead of `interaction` to identify user actions. For more information on Item Actions, refer to the [Item Actions](https://developer.salesforce.com/docs/marketing/personalization/guide/item-actions.md) documentation.

#### Resolvers

Resolvers are a set of properties provided by the Web SDK that help you return the values of page elements and attributes. You can use resolvers with some objects in the preceding table, such as `catalog`, to more easily return item information. Resolvers return functions so that they can be invoked _after_ a page has been matched. When used in a page type configuration, the returned functions don’t need to be invoked to get the final value as the underlying Sitemap code handles that logic.

The following code samples show resolvers being used to return information on line items on an ecommerce site.

```javascript
attributes: {
    name: SalesforceInteractions.resolvers.fromJsonLd("name"),
    description: SalesforceInteractions.resolvers.fromSelector(".short-description", (desc) => desc.trim()),
    url: SalesforceInteractions.resolvers.fromHref(),
    imageUrl: SalesforceInteractions.resolvers.fromSelectorAttribute(".product-carousel .carousel-item[data-slick-index='0'] img", "src", (url) =>  window.location.origin + url)
}
```

```javascript
attributes: {
    name: Evergage.resolvers.fromJsonLd("name"),
    description: Evergage.resolvers.fromSelector(".short-description"),
    url: Evergage.resolvers.fromHref(),
    imageUrl: Evergage.resolvers.fromSelectorAttribute(".product-carousel .carousel-item[data-slick-index='0'] img", "src"),
}
```

**note:** For detailed guidance on implementing resolvers and a complete list of the available resolvers, see [Sitemap Implementation Notes](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.md).

#### Common Object Configuration Examples

The following sections describe and present example configurations of the common Sitemap objects described in the preceding table. The example configurations shown here are taken from the complete [ecommerce Example Sitemap](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps/ecommerce.md).

**Content Zones**

Content Zones are used to designate areas of a page that are potential targets for rendering personalized content from customer engagement campaigns, with each content zone targeting a single zone. This functionality is implemented using a `contentZones` array. Individual Content Zones consist of a `name` defined by you indicating the Content Zone's location on a page and a `selector` to designate the HTML element eligible for personalization. Content Zones can be defined without a `selector`, meaning no designated HTML element is associated with the Content Zone. This usage supports abandonment popups that display when a user begins to browse away from the page.
The following are examples of Content Zone configurations.

```javascript
// Example: "Header" and "Footer" Content Zones defined in the global object configuration

contentZones: [
    { name: "global_infobar_top_of_page", selector: "header.site-header" },
    { name: "global_infobar_bottom_of_page", selector: "footer.site-footer" }
],

// Example: Content Zones defined for product recommendation rows in product detail page type

contentZones: [
    { name: "product_detail_recs_row_1", selector: ".row.recommendations div[id*='cq']:nth-of-type(1)" },
    { name: "product_detail_recs_row_2", selector: ".row.recommendations div[id*='cq']:nth-of-type(2)" },
],

// Example: "Logical" Content Zone defined with no selector for popup in the global object configuration

contentZones: [
    { name: "global_popup" }
],
```

```javascript
// Example: "Header" and "Footer" Content Zones defined in the global object configuration

contentZones: [
    { name: "global_infobar_top_of_page", selector: "header.site-header" },
    { name: "global_infobar_bottom_of_page", selector: "footer.site-footer" }
],

// Example: Content Zones defined for product recommendation rows in product detail page type

contentZones: [
    { name: "product_detail_recs_row_1", selector: ".row.recommendations div[id*='cq']:nth-of-type(1)" },
    { name: "product_detail_recs_row_2", selector: ".row.recommendations div[id*='cq']:nth-of-type(2)" },
],

// Example: "Logical" Content Zone defined with no selector for popup in the global object configuration

contentZones: [
    { name: "global_popup" }
],
```

**note:** For more information and examples of commonly used Content Zones, see [Content Zones](https://developer.salesforce.com/docs/marketing/personalization/guide/content-zones.md).

**Listeners**

Sitemap listeners are used to listen for user actions on a page, capture information from the action, and send that action and information to Personalization. Listeners could be used in the global object configuration and specific page types.

The following are examples of listeners configured in the `global` config and `product_detail` page type.

```javascript
// Example: Listener on the global object for email sign-up that captures user email

listeners: [
    SalesforceInteractions.listener("submit", ".email-signup", () => {
        const email = SalesforceInteractions.cashDom("#dwfrm_mcsubscribe_email").val();
        if (email) {
            SalesforceInteractions.sendEvent({ interaction: { name: "Email Sign Up - Footer" }, user: { identities: { emailAddress: email } } });
        }
    }),
],

// Example: Listener on a product detail page that listens for an add-to-cart action and captures the product line item added

listeners: [
    SalesforceInteractions.listener("click", ".add-to-cart", () => {
        let lineItem = SalesforceInteractions.mcis.buildLineItemFromPageState("select.quantity-select option:checked");
        SalesforceInteractions.sendEvent({
            interaction: {
                name: SalesforceInteractions.CartInteractionName.AddToCart,
                lineItem: lineItem
            }
        });
    }),
],
```

```javascript
// Example: Listener on the global object for email sign-up that captures user email

listeners: [
    Evergage.listener("submit", ".email-signup", () => {
        const email = Evergage.cashDom("#dwfrm_mcsubscribe_email").val();
        if (email) {
            Evergage.sendEvent({action: "Email Sign Up - Footer", user: {id: email} });
        }
    }),
],

// Example: Listener on a product detail page that listens for an add-to-cart action and captures the product line item added

listeners: [
    Evergage.listener("click", ".add-to-cart", () => {
        const lineItem = Evergage.util.buildLineItemFromPageState("select[id*=quantity]");
        lineItem.sku = { _id: Evergage.cashDom(".product-detail[data-pid]").attr("data-pid") };
        Evergage.sendEvent({
            itemAction: Evergage.ItemAction.AddToCart,
            cart: {
                singleLine: {
                    Product: lineItem
                }
            }
        });
    }),
],
```

**note:** For more information on implementing Sitemap listeners, see [Sitemap Implementation Notes](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.md#listeners).

**isMatch**

The `isMatch` property is a required component of each page type configuration in the `pageTypes` array. The `isMatch` property must declare a function that tells Personalization how to determine what type of page the user is viewing. An `isMatch` function can return a boolean, or a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves a boolean.

The following are example configurations of the `isMatch` property.

```javascript
// Example: isMatch property using the Web SDK cashDom function to return the "Product-Show" DOM element which
// would indicate the user is on the Product Detail ("product_detail") page type.

name: "product_detail",
isMatch: () => {
    return SalesforceInteractions.cashDom("div.page[data-action='Product-Show']").length > 0;
}

// Example: isMatch property using a regex expression to return the window href "/cart" which would indicate
// the user is on the shopping cart ("cart") page type.

name: "cart",
isMatch: () => /\/cart/.test(window.location.href),

// Example: isMatch property that returns a Promise

name: "cart",
isMatch: () => {
    return SalesforceInteractions.DisplayUtils.pageElementLoaded(".cart-empty, .cart", "html").then(() => true);
}
```

```javascript
// Example: isMatch property using the Web SDK cashDom function to return the "Product-Show" DOM element which
// would indicate the user is on the Product Detail ("product_detail") page type.

name: "product_detail",
isMatch: () => {
    return Evergage.cashDom("div.page[data-action='Product-Show']").length > 0;
}

// Example: isMatch property using a regex expression to return the window href "/cart" which would indicate
// the user is on the shopping cart ("cart") page type.

name: "cart",
isMatch: () => /\/cart/.test(window.location.href),

// Example: isMatch property that returns a Promise

name: "cart",
isMatch: () => {
    return Evergage.DisplayUtils.pageElementLoaded(".cart-empty, .cart", "html").then(() => true);
}
```

**Capture Catalog Information**

You can capture information on Catalog Objects being viewed through the Sitemap. When using the `SalesforceInteractions` namespace, this information is captured from `interaction.catalogObject` of the matching `pageType` for `ViewCatalogObject` interactions. When using the `Evergage` namespace, this information is captured from the `catalog` object of the matching `pageType`.

The `id` field (or `_id` when using the `Evergage` namespace) is required when tracking a Catalog Object. In the `SalesforceInteractions` namespace, a Promise can be returned for every field of the `catalogObject`. In the `Evergage` namespace, a Promise can be returned for the `_id`, `categories`, and `relatedCatalogObjects` fields. When returning Promises for these fields, the event is tracked only after all Promises resolve.

**important:** Catalog items and attributes must be defined and enabled through the Personalization UI before you can use them in a Sitemap. Some item attributes, like `id`, `name`, and `description`, are built into every catalog item by default. You can add additional attributes for catalog items within the Personalization UI as needed. For more information on defining catalog items and attributes, see [Create a Custom Catalog Object](https://help.salesforce.com/s/articleView?id=sf.mc_pers_catalog_object_custom.htm).

The following are examples of capturing catalog information on a product detail page type.

```javascript
interaction: {
    name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
    catalogObject: {
        type: "Product",
        id: () => {
            return SalesforceInteractions.util.resolveWhenTrue.bind(() => {
                const productId = SalesforceInteractions.cashDom(".product-id").first().text();
                const products = getProductsFromDataLayer();
                if (products && products.length > 0) {
                    return products[0].id;
                } else if (productId) {
                    return productId;
                } else {
                    return false;
                }
            })
        },
        attributes: {
            sku: { id: SalesforceInteractions.cashDom(".product-detail[data-pid]").attr("data-pid") },
            name: SalesforceInteractions.resolvers.fromJsonLd("name"),
            description: SalesforceInteractions.resolvers.fromSelector(".short-description", (desc) => desc.trim()),
            url: SalesforceInteractions.resolvers.fromHref(),
            imageUrl: SalesforceInteractions.resolvers.fromSelectorAttribute(".product-carousel .carousel-item[data-slick-index='0'] img", "src", (url) => window.location.origin + url),
            inventoryCount: 1,
            price: SalesforceInteractions.resolvers.fromSelector(".prices .price .value", (price) => parseFloat(price.replace(/[^0-9\.]+/g, ""))),
            rating: () => {
                return SalesforceInteractions.mcis.extractFirstGroup(/([.\w]+) out of/, SalesforceInteractions.cashDom(".ratings .sr-only").text());
            },
        },
        relatedCatalogObjects: {
            Category: SalesforceInteractions.DisplayUtils.pageElementLoaded(".container .product-breadcrumb .breadcrumb a", "html").then((ele) => {
                return SalesforceInteractions.resolvers.buildCategoryId(".container .product-breadcrumb .breadcrumb a", null, null, (categoryId) => [categoryId.toUpperCase()]);
            }),
            Gender: SalesforceInteractions.DisplayUtils.pageElementLoaded(".product-breadcrumb .breadcrumb a, h1.product-name", "html").then((ele) => {
                if (SalesforceInteractions.cashDom(".product-breadcrumb .breadcrumb a").first().text().toLowerCase() === "women" ||
                    SalesforceInteractions.cashDom("h1.product-name").text().indexOf("Women") >= 0) {
                    return ["WOMEN"];
                } else if (SalesforceInteractions.cashDom(".product-breadcrumb .breadcrumb a").first().text().toLowerCase() === "men" ||
                    SalesforceInteractions.cashDom("h1.product-name").text().indexOf("Men") >= 0) {
                    return ["MEN"];
                } else {
                    return;
                }
            }),
            Color: SalesforceInteractions.DisplayUtils.pageElementLoaded(".attributes", "html").then((ele) => {
                return SalesforceInteractions.resolvers.fromSelectorAttributeMultiple(".color-value", "data-attr-value");
            }),
            Feature: SalesforceInteractions.DisplayUtils.pageElementLoaded(".features", "html").then((ele) => {
                return SalesforceInteractions.resolvers.fromSelectorMultiple(".long-description li", (features) => {
                    return features.map((feature) => {
                        return feature.trim().toUpperCase();
                    })
                })
            })
        }
    }
}
```

```javascript
catalog: {
    Product: {
        _id: () => {
            return Evergage.util.resolveWhenTrue.bind(() => {
                const productId = Evergage.cashDom(".product-id").first().text();
                const products = getProductsFromDataLayer();
                if (products && products.length > 0) {
                    return products[0].id;
                } else if (productId) {
                    return productId;
                } else {
                    return false;
                }
            })
        },
        sku: { _id: Evergage.cashDom(".product-detail[data-pid]").attr("data-pid") },
        name: Evergage.resolvers.fromJsonLd("name"),
        description: Evergage.resolvers.fromSelector(".short-description"),
        url: Evergage.resolvers.fromHref(),
        imageUrl: Evergage.resolvers.fromSelectorAttribute(".product-carousel .carousel-item[data-slick-index='0'] img", "src"),
        inventoryCount: 1,
        price: Evergage.resolvers.fromSelector(".prices .price .value"),
        rating: () => {
            return Evergage.util.extractFirstGroup(/([.\w]+) out of/, Evergage.cashDom(".ratings .sr-only").text());
        },
        categories: () => {
            return Evergage.DisplayUtils.pageElementLoaded(".container .product-breadcrumb .breadcrumb a", "html").then((ele) => {
                return Evergage.resolvers.buildCategoryId(".container .product-breadcrumb .breadcrumb a", null, null, (categoryId) => [categoryId.toUpperCase()]);
            });
        },
        relatedCatalogObjects: { // In case you're using 'dimensions' instead of 'relatedCatalogObjects', you can continue to do so as they both function the same way.
            Gender: () => {
                return Evergage.DisplayUtils.pageElementLoaded(".product-breadcrumb .breadcrumb a, h1.product-name", "html").then((ele) => {
                    if (Evergage.cashDom(".product-breadcrumb .breadcrumb a").first().text().toLowerCase() === "women" ||
                        Evergage.cashDom("h1.product-name").text().indexOf("Women") >= 0) {
                        return ["WOMEN"];
                    } else if (Evergage.cashDom(".product-breadcrumb .breadcrumb a").first().text().toLowerCase() === "men" ||
                        Evergage.cashDom("h1.product-name").text().indexOf("Men") >= 0) {
                        return ["MEN"];
                    } else {
                        return;
                    }
                });
            },
            Color: () => {
                return Evergage.DisplayUtils.pageElementLoaded(".attributes", "html").then((ele) => {
                    return Evergage.resolvers.fromSelectorAttributeMultiple(".color-value", "data-attr-value");
                });
            },
            Feature: () => {
                return Evergage.DisplayUtils.pageElementLoaded(".features", "html").then((ele) => {
                    return Evergage.resolvers.fromSelectorMultiple(".features .feature", (features) => {
                        return features.map((feature) => {
                            return feature.trim();
                        });
                    });
                });
            }
        }
    }
}
```

**Capture Cart Information**

You can capture information on the user's `cart` through the Sitemap. When using the `SalesforceInteractions` namespace, this information is captured from `interaction.lineItems` of the matching pageType for `ReplaceCart` interactions. When using the `Evergage` namespace, this information is captured from the `cart` object.

Capturing information about the user's `cart` is typically used in the shopping cart pages of ecommerce sites to collect information about line items, including the item ID (or SKU), price, and quantity. When using the `Evergage` namespace, the `_id`, `price`, and `quantity` fields of a cart object can return a Promise. When returning Promises for these fields, an event is sent only if all Promises resolve.

The following are examples of capturing cart information from a cart page type.

**note:** In the `SalesforceInteractions` namespace, you can use the `ReplaceCart` interaction to update the state of the cart in Personalization by setting its content to the provided line items while replacing the previous cart contents.

```javascript
// Example: Without SKU
interaction: {
	name: SalesforceInteractions.CartInteractionName.ReplaceCart,
	lineItems: SalesforceInteractions.DisplayUtils.pageElementLoaded(".cart-empty, .checkout-btn", "html").then(() => {
		let cartLineItems = [];
		SalesforceInteractions.cashDom(".product-info .product-details").each((index, ele) => {
			let itemQuantity = parseInt(SalesforceInteractions.cashDom(ele).find(".qty-card-quantity-count").text().trim());
			if (itemQuantity && itemQuantity > 0) {
				let lineItem = {
					catalogObjectType: "Product",
					catalogObjectId: SalesforceInteractions.cashDom(ele).find(".line-item-quantity-info").attr("data-pid").trim(),
					price: SalesforceInteractions.cashDom(ele).find(".pricing").text().trim().replace(/[^0-9\.]+/g, "") / itemQuantity,
					quantity: itemQuantity
				};
				cartLineItems.push(lineItem);
			}
		})
		return cartLineItems;
	})
}

// Example: With SKU
interaction: {
	name: SalesforceInteractions.CartInteractionName.ReplaceCart,
	lineItems: SalesforceInteractions.DisplayUtils.pageElementLoaded(".cart-empty, .checkout-btn", "html").then(() => {
		let cartLineItems = [];
		SalesforceInteractions.cashDom(".product-info .product-details").each((index, ele) => {
			let itemQuantity = parseInt(SalesforceInteractions.cashDom(ele).find(".qty-card-quantity-count").text().trim());
			if (itemQuantity && itemQuantity > 0) {
				let lineItem = {
					catalogObjectType: "Product",
					price: SalesforceInteractions.cashDom(ele).find(".pricing").text().trim().replace(/[^0-9\.]+/g, "") / itemQuantity,
					quantity: itemQuantity,
					attributes: {
						sku: {
							id: SalesforceInteractions.cashDom(ele).find(".line-item-quantity-info").attr("data-sku").trim()
						}
					}
				};
				cartLineItems.push(lineItem);
			}
		})
		return cartLineItems;
	})
}
```

**note:** In the `Evergage` namespace, you can use the `cart.complete` object to update the state of the cart in Personalization by setting its content to the provided line items while replacing previous cart contents.

```javascript
cart: {
    complete: {
        Product: {
            _id: () => {
                return Evergage.DisplayUtils.pageElementLoaded(".cart-empty, .checkout-btn", "html").then((ele) => {
                    return Evergage.resolvers.fromSelectorAttributeMultiple(".product-info .product-details .line-item-quantity-info", "data-pid")
                })
            },
            price: () => {
                return Evergage.DisplayUtils.pageElementLoaded(".cart-empty, .checkout-btn", "html").then((ele) => {
                    return Evergage.resolvers.fromSelectorMultiple(".product-info .product-details .pricing");
                })
            },
            quantity: () => {
                return Evergage.DisplayUtils.pageElementLoaded('.cart-empty, .checkout-btn', "html").then((ele) => {
                    return Evergage.resolvers.fromSelectorMultiple(".product-info .product-details .qty-card-quantity-count");
                });
            }
        }
    }
}
```

**Capture Order Information**

Orders are typically used in the order confirmation pages of ecommerce sites to collect information about the line items in a transaction, including the item ID (or SKU), price, and quantity.

When using the `SalesforceInteractions` namespace, this information is captured from `interaction.order` of the matching pageType for `Purchase` interactions. When using the `Evergage` namespace, this information is captured from the `order` object.

In the `Evergage` namespace, an `order` object can return Promises for all fields. When returning Promises, an event is sent only after all Promises resolve.

**note:** - The `resolver` functions in the Personalization Web SDK are especially useful in simplifying the retrieval of this data.
- In the `Evergage` namespace, you must define an `_id` field under item type. However, if they’re properly attributed to a product, you can pass SKU values here instead of the `_id` field.

The following are examples of capturing order information from an order confirmation page type.

```javascript
// Example: Without SKU
interaction: {
	name: SalesforceInteractions.OrderInteractionName.Purchase,
	order: {
		id: SalesforceInteractions.DisplayUtils.pageElementLoaded(".order-number", "html").then((ele) => {
			return SalesforceInteractions.resolvers.fromSelector(".order-number");
		}),
		lineItems: SalesforceInteractions.DisplayUtils.pageElementLoaded(".product-line-item", "html").then(() => {
			let purchaseLineItems = [];
			SalesforceInteractions.cashDom(".product-line-item").each((index, ele) => {
				let itemQuantity = parseInt(SalesforceInteractions.cashDom(ele).find(".qty-card-quantity-count").text().trim());
				if (itemQuantity && itemQuantity > 0) {
					let lineItem = {
						catalogObjectType: "Product",
						catalogObjectId: SalesforceInteractions.cashDom(ele).find(".line-item-quantity-info").attr("data-pid").trim(),
						price: SalesforceInteractions.cashDom(ele).find(".pricing").text().trim().replace(/[^0-9\.]+/g, "") / itemQuantity,
						quantity: itemQuantity
					};
					purchaseLineItems.push(lineItem);
				}
			})
			return purchaseLineItems;
		})
	}
}

// Example: With SKU
interaction: {
	name: SalesforceInteractions.OrderInteractionName.Purchase,
	order: {
		id: SalesforceInteractions.DisplayUtils.pageElementLoaded(".order-number", "html").then((ele) => {
			return SalesforceInteractions.resolvers.fromSelector(".order-number");
		}),
		lineItems: SalesforceInteractions.DisplayUtils.pageElementLoaded(".product-line-item", "html").then(() => {
			let purchaseLineItems = [];
			SalesforceInteractions.cashDom(".product-line-item").each((index, ele) => {
				let itemQuantity = parseInt(SalesforceInteractions.cashDom(ele).find(".qty-card-quantity-count").text().trim());
				if (itemQuantity && itemQuantity > 0) {
					let lineItem = {
						catalogObjectType: "Product",
						price: SalesforceInteractions.cashDom(ele).find(".pricing").text().trim().replace(/[^0-9\.]+/g, "") / itemQuantity,
						quantity: itemQuantity,
						attributes: {
							sku: {
								id: SalesforceInteractions.cashDom(ele).find(".line-item-quantity-info").attr("data-sku").trim()
							}
						}
					};
					purchaseLineItems.push(lineItem);
				}
			})
			return purchaseLineItems;
		})
	}
}
```

```javascript
order: {
    Product: {
        orderId: () => {
            return Evergage.DisplayUtils.pageElementLoaded(".order-number", "html").then((ele) => {
                return Evergage.resolvers.fromSelector(".order-number");
            });
        },
        lineItems: {
            _id: () => {
                return Evergage.DisplayUtils.pageElementLoaded(".product-line-item line-item-quantity-info", "html").then((ele) => {
                    return Evergage.resolvers.fromSelectorAttributeMultiple(".product-line-item .line-item-quantity-info", "data-pid");
                });
            },
            price:  () => {
                return Evergage.DisplayUtils.pageElementLoaded(".product-line-item .pricing", "html").then((ele) => {
                    return Evergage.resolvers.fromSelectorAttributeMultiple(".product-line-item .pricing", "data-pid");
                });
            },
            quantity:  () => {
                return Evergage.DisplayUtils.pageElementLoaded(".product-line-item .qty-card-quantity-count", "html").then((ele) => {
                    return Evergage.resolvers.fromSelectorAttributeMultiple(".product-line-item .qty-card-quantity-count", "data-pid");
                });
            }
        }
    }
}
```

**Action**

The `action` property provides a way for Personalization to name user actions such as viewing the page or signing up for an email subscription. An `action` property is often included after the `name` in the page type specification.

The following example code sends a "Login" action to Personalization every time a user accesses the `login` page type.

**important:** The `action` property is available exclusively in the `Evergage` namespace.

```javascript
{
  name: "login",
  action: "Login",
  isMatch: () => /\/login/.test(window.location.href)
}
```

**Interaction**

An `interaction` property is used to identify specific actions users take. Examples of `interaction` values include `AddToCart`, `Purchase`, and `Comment`. For a complete list of `interaction` values, refer to [Interaction Definitions](https://developer.salesforce.com/docs/marketing/personalization/guide/interaction-definitions.md).

**important:** The `interaction` property is available exclusively in the `SalesforceInteractions` namespace. If you're using the `Evergage` namespace within your Sitemap code, you must continue to use the `itemAction` property instead of `interaction` to identify user actions. For more information on Item Actions, refer to the [Item Actions](https://developer.salesforce.com/docs/marketing/personalization/guide/item-actions.md) documentation.

The following is an example of using the `interaction` property in the `SalesforceInteractions` namespace in Sitemap code.

```javascript
// Example: Send Add-to-cart Interaction

SalesforceInteractions.sendEvent({
    interaction: {
        name: SalesforceInteractions.CartInteractionName.AddToCart,
        lineItem: lineItem
    }
});

// Example: Replace Cart Interaction on a shopping cart page

name: "cart",
isMatch: () => /\/cart/.test(window.location.href),
interaction: {
    name: SalesforceInteractions.CartInteractionName.ReplaceCart,
    lineItems: lineItems
}

// Example: Purchase Interaction on an order confirmation page

name: "order_confirmation",
isMatch: () => /\/confirmation/.test(window.location.href),
interaction: {
    name: SalesforceInteractions.OrderInteractionName.Purchase,
    order: {
        //order configuration
    }
}
```

The following is an example of using the `itemAction` property within in the `Evergage` namespace in Sitemap code.

```javascript
// Example: Send Add-to-cart item action as an event

Evergage.sendEvent({
    itemAction: Evergage.ItemAction.AddToCart
    cart: {
        singleLine: {
            Product: lineItem
        }
    }
});

// Example: View-cart item action on a shopping cart page

name: "cart",
isMatch: () => /\/cart/.test(window.location.href),
itemAction: Evergage.ItemAction.ViewCart
cart: {
    //cart config
}

// Example: Purchase item action on an order confirmation page

name: "order_confirmation",
isMatch: () => /\/confirmation/.test(window.location.href),
itemAction: Evergage.ItemAction.Purchase,
order: {
    //order configuration
}
```

**onActionEvent**

The `onActionEvent` function is used with the `ActionEvent` property to send events to Personalization based on user actions.

The following code samples depict the usage of the `onActionEvent` function in the `pageType` configuration in each of the SDK namespaces.

```javascript
pageTypes: [
  {
    name: "search",
    isMatch: () => /\/search/.test(window.location.pathname),
    onActionEvent: (actionEvent) => {
      const searchTerm = SalesforceInteractions.cashDom(".content.searchTerm").text().trim();
      if (searchTerm) {
        actionEvent.user = actionEvent.user || {};
        actionEvent.user.attributes = actionEvent.user.attributes || {};
        actionEvent.user.attributes.lastSearchTerm = searchTerm;
      }
      return actionEvent;
    },
  },
];
```

```javascript
pageTypes: [
  {
    name: "search",
    isMatch: () => /\/search/.test(window.location.pathname),
    onActionEvent: (actionEvent) => {
      const searchTerm = Evergage.cashDom(".content.searchTerm").text().trim();
      if (searchTerm) {
        actionEvent.user = actionEvent.user || {};
        actionEvent.user.attributes = actionEvent.user.attributes || {};
        actionEvent.user.attributes.lastSearchTerm = searchTerm;
      }
      return actionEvent;
    },
  },
];
```

### Configure the Global Sitemap Object

The `global` Sitemap configuration object allows you to define what to capture on every page that is matched as a page type. The `global` Sitemap object enables you to define Content Zones, listeners, locale, and `onActionEvent` functions for every page that is matched instead of only on individually matched pages.

The following shows an example of a `global` Sitemap configuration.

```javascript
SalesforceInteractions.init({
    cookieDomain: "northerntrailoutfitters.com"
}).then(() => {
    const sitemapConfig = {
        global: {
            contentZones: [
                {name: "global_infobar_top_of_page", selector: "header.site-header"},
                {name: "global_infobar_bottom_of_page", selector: "footer.site-footer"},
                {name: "global_popup" }
            ],
            listeners: [
                SalesforceInteractions.listener("submit", ".email-signup", () => {
                    const email = SalesforceInteractions.cashDom("#dwfrm_mcsubscribe_email").val();
                    if (email) {
                        SalesforceInteractions.sendEvent({ interaction: { name: "Email Sign Up - Footer" }, user: { identities: { emailAddress: email } } });
                    }
                }),
            ],
        },
        pageTypes: [ // ...page type configurations...]
    }

    SalesforceInteractions.initSitemap(sitemapConfig);
});
```

```javascript
Evergage.init({
    cookieDomain: "northerntrailoutfitters.com"
}).then(() => {
    const sitemapConfig = {
        global: {
            contentZones: [
                {name: "global_infobar_top_of_page", selector: "header.site-header"},
                {name: "global_infobar_bottom_of_page", selector: "footer.site-footer"},
                {name: "global_popup" }
            ],
            listeners: [
                Evergage.listener("submit", ".email-signup", () => {
                    const email = Evergage.cashDom("#dwfrm_mcsubscribe_email").val();
                    if (email) {
                        Evergage.sendEvent({action: "Email Sign Up - Footer", user: {id: email} });
                    }
                }),
            ],
        },
        pageTypes: [ // ...page type configurations...]
    }

    Evergage.initSitemap(sitemapConfig);
});
```

## Configure Page Type Array Objects

A Sitemap configuration consists of the [`global` configuration](#configure-the-global-sitemap-object), which runs for all page types, and an array of individual page type configurations. At a minimum, a page type requires configuring a `name` and an `isMatch` function. The `name` defines the name of the page type, while the `isMatch` function output is evaluated to determine if the page the user is on matches the page configuration. After `name` and `isMatch`, you can use any of the `sitemapConfig` objects mentioned in this article in a page type configuration object.

The following code sample depicts a sample page type configuration.

```javascript
{
  name: string
  isMatch: () => boolean | () => Promise<boolean>
}
```

The `isMatch` function accepts a function that returns a boolean or a Promise. The sitemap evaluates only the first page type whose `isMatch` resolves to `true`. If no page types match, no event is sent to Personalization.

The following are examples of different page type configurations in each SDK namespace.

```javascript
SalesforceInteractions.init({
  cookieDomain: "northerntrailoutfitters.com",
}).then(() => {
  const config = {
    global: {
      onActionEvent: (actionEvent) => {
        const email = SalesforceInteractions.mcis.getValueFromNestedObject(
          "window._etmc.user_info.email",
        );
        if (email) {
          actionEvent.user = actionEvent.user || {};
          actionEvent.user.identities = actionEvent.user.identities || {};
          actionEvent.user.identities.emailAddress = email;
        }
        return actionEvent;
      },
      contentZones: [
        { name: "global_infobar_top_of_page", selector: "header.site-header" },
        { name: "global_infobar_bottom_of_page", selector: "footer.site-footer" },
      ],
      listeners: [
        SalesforceInteractions.listener("submit", ".email-signup", () => {
          const email = SalesforceInteractions.cashDom("#dwfrm_mcsubscribe_email").val();
          if (email) {
            SalesforceInteractions.sendEvent({
              interaction: { name: "Email Sign Up - Footer Test" },
              user: { identities: { emailAddress: email } },
            });
          }
        }),
      ],
    },
    pageTypes: [
      {
        name: "home",
        isMatch: () => /\/homepage/.test(window.location.href),
        interaction: {
          name: "Homepage",
        },
        contentZones: [
          { name: "home_hero", selector: ".experience-carousel-bannerCarousel" },
          {
            name: "home_sub_hero",
            selector: ".experience-carousel-bannerCarousel + .experience-component",
          },
          { name: "home_popup" },
        ],
      },
      {
        name: "login",
        action: "Login",
        isMatch: () =>
          /\/login/.test(window.location.href) &&
          window.location.hostname !== "community.northerntrailoutfitters.com",
        listeners: [
          SalesforceInteractions.listener("click", "form[name='login-form'] button", () => {
            const email = SalesforceInteractions.cashDom("#login-form-email").val();
            if (email) {
              SalesforceInteractions.sendEvent({
                action: "Logged In",
                user: { attributes: { emailAddress: email } },
              });
            }
          }),
        ],
      },
      {
        name: "cart",
        isMatch: () => /\/cart/.test(window.location.href),
        interaction: {
          name: SalesforceInteractions.CartInteractionName.ReplaceCart,
          lineItems: SalesforceInteractions.DisplayUtils.pageElementLoaded(
            ".cart-empty, .checkout-btn",
            "html",
          ).then(() => {
            let cartLineItems = [];
            SalesforceInteractions.cashDom(".product-info .product-details").each(
              (index, ele) => {
                let itemQuantity = parseInt(
                  SalesforceInteractions.cashDom(ele)
                    .find(".qty-card-quantity-count")
                    .text()
                    .trim(),
                );
                if (itemQuantity && itemQuantity > 0) {
                  let lineItem = {
                    catalogObjectType: "Product",
                    catalogObjectId: SalesforceInteractions.cashDom(ele)
                      .find(".line-item-quantity-info")
                      .attr("data-pid")
                      .trim(),
                    price:
                      SalesforceInteractions.cashDom(ele)
                        .find(".pricing")
                        .text()
                        .trim()
                        .replace(/[^0-9\.]+/g, "") / itemQuantity,
                    quantity: itemQuantity,
                  };
                  cartLineItems.push(lineItem);
                }
              },
            );
            return cartLineItems;
          }),
        },
      },
    ],
  };
  SalesforceInteractions.initSitemap(config);
});
```

```javascript
Evergage.init({
  cookieDomain: "northerntrailoutfitters.com",
}).then(() => {
  const config = {
    global: {
      onActionEvent: (actionEvent) => {
        const email = Evergage.util.getValueFromNestedObject("window._etmc.user_info.email");
        if (email) {
          actionEvent.user = actionEvent.user || {};
          actionEvent.user.attributes = actionEvent.user.attributes || {};
          actionEvent.user.attributes.emailAddress = email;
        }
        return actionEvent;
      },
      contentZones: [
        { name: "global_infobar_top_of_page", selector: "header.site-header" },
        { name: "global_infobar_bottom_of_page", selector: "footer.site-footer" },
      ],
      listeners: [
        Evergage.listener("submit", ".email-signup", () => {
          const email = Evergage.cashDom("#dwfrm_mcsubscribe_email").val();
          if (email) {
            Evergage.sendEvent({
              action: "Email Sign Up - Footer",
              user: { attributes: { emailAddress: email } },
            });
          }
        }),
      ],
    },
    pageTypes: [
      {
        name: "home",
        action: "Homepage",
        isMatch: () => /\/homepage/.test(window.location.href),
        contentZones: [
          { name: "home_hero", selector: ".experience-carousel-bannerCarousel" },
          {
            name: "home_sub_hero",
            selector: ".experience-carousel-bannerCarousel + .experience-component",
          },
          { name: "home_popup" },
        ],
      },
      {
        name: "login",
        action: "Login",
        isMatch: () =>
          /\/login/.test(window.location.href) &&
          window.location.hostname !== "community.northerntrailoutfitters.com",
        listeners: [
          Evergage.listener("click", "form[name='login-form'] button", () => {
            const email = Evergage.cashDom("#login-form-email").val();
            if (email) {
              Evergage.sendEvent({
                action: "Logged In",
                user: { attributes: { emailAddress: email } },
              });
            }
          }),
        ],
      },
      {
        name: "cart",
        isMatch: () => /\/cart/.test(window.location.href),
        itemAction: Evergage.ItemAction.ViewCart,
        catalog: {
          Product: {
            lineItems: {
              _id: () => {
                return Evergage.DisplayUtils.pageElementLoaded(
                  ".cart-empty, .checkout-btn",
                  "html",
                ).then((ele) => {
                  return Evergage.resolvers.fromSelectorAttributeMultiple(
                    ".product-info .product-details .line-item-quantity-info",
                    "data-pid",
                  );
                });
              },
              price: () => {
                return Evergage.DisplayUtils.pageElementLoaded(
                  ".cart-empty, .checkout-btn",
                  "html",
                ).then((ele) => {
                  return Evergage.resolvers.fromSelectorMultiple(
                    ".product-info .product-details .pricing",
                  );
                });
              },
              quantity: () => {
                return Evergage.DisplayUtils.pageElementLoaded(
                  ".cart-empty, .checkout-btn",
                  "html",
                ).then((ele) => {
                  return Evergage.resolvers.fromSelectorMultiple(
                    ".product-info .product-details .qty-card-quantity-count",
                  );
                });
              },
            },
          },
        },
      },
    ],
  };
  Evergage.initSitemap(config);
});
```

**note:** For additional examples of page type configurations and complete Sitemaps, see [Example Sitemaps](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps.md).

## Initialize the Sitemap

A Sitemap is initialized at the end of the JavaScript code by calling `SalesforceInteractions.initSitemap(sitemapConfig)` in the `SalesforceInteractions` namespace or `Evergage.initSitemap(sitemapConfig)` in the `Evergage` namespace. Sitemap events aren’t tracked unless the sitemap is initialized by calling either of those functions _and_ until a matching page type is found. If your sitemap has errors or if no matching page types are found, you can encounter errors.

The following code sample depicts the initialization of a Sitemap using `SalesforceInteractions.initSitemap(sitemapConfig)` in the `SalesforceInteractions` namespace.

```javascript
SalesforceInteractions.init({
    cookieDomain: "developer.evergage.com"
}).then(() => {

    const sitemapConfig = {
        global: {...global object configuration...},
        pageTypes: [...page type array configuration...]
    }

    SalesforceInteractions.initSitemap(sitemapConfig);
});
```

The following code sample depicts the initialization of a Sitemap using `Evergage.initSitemap(sitemapConfig)` in the `Evergage` namespace.

```javascript
Evergage.init({
    cookieDomain: "developer.evergage.com"
}).then(() => {

    const sitemapConfig = {
        global: {...global object configuration...},
        pageTypes: [...page type array configuration...]
    }

    Evergage.initSitemap(sitemapConfig);
});
```

## See Also

- [_Salesforce Help_: Install the Salesforce Interactions SDK Launcher](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_interactions_sdk_launcher.htm)
- [_Salesforce Help_: Create a Custom Catalog Object](https://help.salesforce.com/s/articleView?id=sf.mc_pers_catalog_object_custom.htm)

<!-- document id=f07b582df1d55289ba2455951e1878f27a96a1bc6b401c010efea913be1cde7c url=/developer/current/en-us/personalization/personalization/guides/campaign-development/open-time-email-campaigns-templates/image-generation-email-campaigns.md -->

# Image Generation in Open Time Email Campaigns

Open Time Email (OTE) campaigns and templates use image generation as a background process. When you publish an OTE template, the image generation process kicks off and determines whether eligible products and associated OTE Item Templates need images. It then creates an initial set of images for all items that match the item type of the template and stores them on the Marketing Cloud Personalization CDN. The images generated by this process appear in the OTE Simulator and the emails you provision via OTE campaigns.

## Common Problems & Causes

The following table describes common problems that can occur with images in OTE campaigns and their causes.

| Problem                                                                             | Causes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Missing or invisible images                                                         | Occurs because there was an error in processing an image generation, which could be due misconfiguration, such as when using locales, or customer CDN throttling limits.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Blurry images                                                                       | Adding style, height, and width tags can cause blurriness. These tags aren’t necessary in order to generate images. In fact, images without style tags appear crisper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Differences between OTE Simulator and test emails                                   | Occurs due to an error with the `customerID` in the test email or because the recipe returns a different result when the test email is opened.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Differences between OTE Simulator and Recipe Simulator or OTE Item Template preview | Occurs because the OTE Simulator uses the images in the CDN, whereas the other features providing previews or simulation don’t.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Differences between images and current product data                                 | Occurs because the product and item template pair hasn’t been identified as needing image generation. Products are tagged for image generation only if they meet eligibility requirements and have properties referenced in a published item template that have changed values. Factors that determine image generation eligibility: <li> Products must be eligible, NOT archived, NOT expired, have a name, URL, `imageURL`, and be in stock (that is, inventory > 0) in order to be considered. </li> <li> If the `imageURL` doesn't change but the image at the URL is modified, the CDN image doesn't get updated. </li> <li> If a product's values not referenced in the OTE item template are altered, the CDN image for that product and item template pair will not be updated. </li> <li> If locales are enabled, there may be issues if the default locale is not properly set. </li> |

## Limitations

Image generation errors that occur due to customer throttling limits are outside of the control of Marketing Cloud Personalization. These errors usually appear as default transparent pixel images, or erroneous images with missing data. You can find additional error information in internal logs.

## Troubleshooting

There are a few things you can do to troubleshoot and fix issues related to images in OTE campaigns and templates.

### Throttling Issues

To fix throttling issues, see if adding the following user agent and HTTP headers to an allowlist to either avoid throttling or have a higher threshold:

| Where       | Add to Allowlist                                                                                                                                           |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HTTP Header | `'X-Salesforce-Agent': 'Interaction Studio Open-Time Email Image Generator`                                                                                |
| User Agent  | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.117 Safari/537.36 Salesforce (InteractionStudio)` |

### Blurry Images

You can improve the clarity of images in your templates by making a few changes to your Personalization OTE and Salesforce Marketing Cloud templates.

#### Personalization OTE Template Changes

1. Clone the Personalization OTE template with blurry images.
2. Add the exact HTML comment `<!--useHidpi-->` to any valid HTML position in the template. For example, you can prepend the HTML comment at the beginning of the OTE template.

   **important:** This comment is case-sensitive.

#### Marketing Cloud Template Changes

1. Specify width constraints for the Personalization OTE template's image slots. For example, if the image slots on your Personalization OTE template are 190 px wide:

   - Add the attribute `width="190"` (without `px`) to the `<img>` tag that uses the OTE image as its `src`.
   - Modify the `style` attribute to include `width: 100%; max-width: 190px`.

   **note:** The width and height of image containers could require adjustments based on the HTML structure and desired final appearance. Keep in mind that standard CSS rules apply when using OTE images in HTML documents.

2. Use the template in a new campaign that uses the cloned HiDPI version of the original Personalization OTE template.

   **important:** If you've already deployed the original campaign with blurry images, you must carry out this step in production.

<!-- document id=52b6541041e2d22d750e1a869df1da00c59ea74373e2d2f87de61785769127d6 url=/developer/current/en-us/personalization/personalization/guides/data-ingestion.md -->

# Ingesting Data into Marketing Cloud Personalization

Marketing Cloud Personalization Feeds is a built-in data-feed processing capability that enables the ingestion of data from external sources. Feeds are a specific type of Personalization Gear extension that provides the pathways to ingest external data files and translate their contents into the Personalization platform. With Feeds, you can update the company catalog, import and export market segments, load historical data, and perform other tasks manually or automatically. After you configure a Feed, Personalization business users can use the **Feeds Dashboard** to view, monitor, and manage Feed data file processing.

Companies are responsible for creating, structuring, and providing data files that meet Personalization specifications. However, Personalization Gear developers are responsible for configuring the Feed pathways that support these data files.

## Deploying Personalization Data Feeds

To review implementation details and learn how to use Personalization data feeds, see [About ETL Data Feeds](https://help.salesforce.com/s/articleView?id=sf.mc_pers_etl_integration_about.htm) on Salesforce Help.

## See Also

- [_Salesforce Help_: About ETL Data Feeds](https://help.salesforce.com/s/articleView?id=sf.mc_pers_etl_integration_about.htm)

<!-- document id=6f595fc8db3ddaef57dbe65e7c4fe3c954237eecd66a2105928b23718631c2f7 url=/developer/current/en-us/personalization/personalization/guides/web-integration/integrate-javascript-beacon.md -->

# Integrate the JavaScript Beacon

The Marketing Cloud Personalization module of the Salesforce Interactions SDK uses a JavaScript beacon to monitor and track the online behavior of your organization’s web users.

**note:** Before you integrate the JavaScript beacon, determine whether you want to use synchronous or asynchronous integration. For more information, see [Synchronous or Asynchronous Integration](https://developer.salesforce.com/docs/marketing/personalization/guide/web-integration-considerations.md#synchronous-or-asynchronous-integration).

This integration process uses the Personalization content delivery network (CDN) to host the JavaScript beacon. To assume responsibility for hosting the JavaScript beacon on your organization’s CDN, see [Self-Host the Server-Side JavaScript Beacon](#self-host-the-server-side-javascript-beacon).

1. Log in to Personalization as an administrator.
2. From the **Channels & Campaigns** section of the main navigation, select **Web** > **JavaScript Integration**.
3. If you have more than one dataset, select the one you want from the dropdown at the top.
4. Click the tab for the type of integration you want: **Synchronous** or **Asynchronous**.
5. Copy the integration code for that type and place it into the HTML head element of your website to ensure that the beacon loads on every page.
6. Repeat this process for any other datasets you have.
7. After integration, if necessary, you can disable the JavaScript beacon by selecting **Web | Web SDK Settings** from the **Channels & Campaigns** section of the main navigation, selecting the **Disabled** toggle, and clicking **Save**.
   Selecting **Disabled** replaces the existing JavaScript beacon with an empty JavaScript resource. All event receipt, analytics, and messaging stop immediately, and propagates in minutes as viewers' browser caches expire.

## Self-Host the Server-Side JavaScript Beacon

Before proceeding with self-hosting the JavaScript beacon, consider the following critical aspects of doing so:

**important:** You must automate updating your SDK from the source SDK that Personalization hosts. The contents of the SDK are dynamic, so if you change various settings in Personalization, change installed gears, or make updates to your site map, the contents of the SDK can also change. If you don't update your hosted version of the SDK in tandem, your campaigns and tracking can break. At a minimum, configure the automated update to check for changes every hour.

To self-host the JavaScript beacon, you must first obtain the JavaScript beacon code and then deploy it to your organization's CDN.

1. Log in to Personalization as an administrator.
2. From the **Channels & Campaigns** section of the main navigation, select **Web** > **JavaScript Integration**.
3. If you have more than one dataset, select the one you want from the dropdown at the top.
4. Click the **Synchronous** tab.
5. Copy the source URL, which begins after `src="https://developer.salesforce.com/docs/marketing/personalization/guide/%60,%20from%20the%20integration%20code.%20For%20example,%20%60//cdn.evgnet.com/beacon/myaccount/mydataset/scripts/evergage.min.js%60.%20This%20link%20provides%20access%20to%20the%20JavaScript%20beacon%20code,%20which%20you%20can%20then%20deploy%20on%20your%20organization's CDN to self-host the JavaScript beacon.

<!-- document id=1b1c39895c574c52ccc1ecda0bddb96a3746e94bfb7062280e8a99d0e081b4cb url=/developer/current/en-us/personalization/personalization/guides/web-integration/interaction-definitions.md -->

# Interaction Definitions

The Salesforce Interactions SDK provides interactions names used to identify certain user interactions related to `Catalog`, `cart`, and `order` objects.

Interactions contain a reserved `name` property and value that Personalization uses to determine how to treat event data.

**important:** The Interactions documented in this article are available exclusively in the `SalesforceInteractions` namespace. In the `Evergage` namespace, Interactions are called Item Actions. For more information, refer to the [Item Actions](https://developer.salesforce.com/docs/marketing/personalization/guide/item-actions.md) documentation.

## Interactions in the Event API

An example of an event sent using the API within the Sitemap can be found in our [Example ecommerce Sitemap](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps/ecommerce.md) within the `"product_detail"` pageType configuration. The following code sample includes the relevant code block. In this example, a listener has been mapped containing an `AddToCart` event that fires when the user clicks the DOM element referenced by the provided selector, `".add-to-cart"`.

```javascript
listeners: [
    SalesforceInteractions.listener("click", ".add-to-cart", () => {
        let lineItem = SalesforceInteractions.mcis.buildLineItemFromPageState("select.quantity-select option:checked");
        SalesforceInteractions.sendEvent({
            interaction: {
                name: SalesforceInteractions.CartInteractionName.AddToCart,
                lineItem: lineItem
            }
        });
    })
],
```

## Reserved Interaction Values

When tracking Catalog Object Interactions, Cart Interactions, or Order Interactions, you have to reference all values assigned to the `interaction.name` property from the `SalesforceInteractions` object. The `SalesforceInteractions` namespace provides the following objects.

- `SalesforceInteractions.CatalogObjectInteractionName`
- `SalesforceInteractions.CartInteractionName`
- `SalesforceInteractions.OrderInteractionName`

## Special Interaction Values

- `SalesforceInteractions.CatalogObjectInteractionName.QuickViewCatalogObject` - Similar to `CatalogObjectInteractionName.ViewCatalogObject` but stops the timer for the "background" item and starts a timer for the "foreground" item.
- `SalesforceInteractions.mcis.CatalogObjectInteractionName.StopQuickViewCatalogObject` - Stops the timer initiated by the "Quick View Item" interaction for the "foreground" item and restarts the timer for the "background" item.

`QuickViewCatalogObject` and `StopQuickViewCatalogObject` are used to accurately track view time in cases where a user "views" an item while already viewing a different item. An ecommerce category page that allows users to view individual products in a window can take advantage of these interactions. In the following example, the "background" item is the category and the "foreground" item is the product. A new page load stops both timers.

```javascript
{
    name: "Category",
        isMatch: () => new Promise((resolve, reject) => {
            let isMatchCat = setTimeout(() => {
                resolve(false);
            }, 50);
            return SalesforceInteractions.DisplayUtils.pageElementLoaded("#product-search-results", "html").then(() => {
                clearTimeout(isMatchCat);
                resolve(SalesforceInteractions.cashDom(".breadcrumb").length > 0);
            });
        }),
        interaction: {
            name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
            catalogObject: {
                type: "Category",
                id: SalesforceInteractions.DisplayUtils.pageElementLoaded(".breadcrumb .breadcrumb-item a", "html").then((ele) => {
                    return SalesforceInteractions.resolvers.buildCategoryId(".breadcrumb .breadcrumb-item a", 1, null, (categoryId) => categoryId.toUpperCase());
                })
            }
        }
    },
    listeners: [
        SalesforceInteractions.listener("click", ".quickview", (e) => {
            const pid = SalesforceInteractions.cashDom(e.target).attr("href").split("pid=")[1];
            if (!pid) {
                return;
            }

            SalesforceInteractions.sendEvent({
                interaction: {
                    name: SalesforceInteractions.CatalogObjectInteractionName.QuickViewCatalogObject,
                    catalogObject: {
                        type: "Product",
                        id: pid
                    }
                }
            });
        }),
        SalesforceInteractions.listener("click", "body", (e) => {
            if (SalesforceInteractions.cashDom(e.target).closest("button[data-dismiss='modal']").length > 0) {
                SalesforceInteractions.sendEvent({
                    interaction: {
                        name: SalesforceInteractions.mcis.CatalogObjectInteractionName.StopQuickViewCatalogObject,
                    }
                });
            } else if (SalesforceInteractions.cashDom(e.target).closest("#quickViewModal").length > 0
                && SalesforceInteractions.cashDom(e.target).find("#quickViewModal .modal-dialog").length > 0) {
                SalesforceInteractions.sendEvent({
                    interaction: {
                        name: SalesforceInteractions.mcis.CatalogObjectInteractionName.StopQuickViewCatalogObject,
                    }
                });
            }
        })
    ]
}
```

## Currently Supported Interactions

Only the `interactions` documented here are currently supported. Unless otherwise indicated, the following definitions apply to both the page config and Event API.

### CatalogObjectInteraction

#### View Catalog Object

```javascript
{
    interaction: {
        name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,
        catalogObject: CatalogObject
    }
}
```

#### View Catalog Object Detail

```javascript
{
    interaction: {
        name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObjectDetail,
        catalogObject: CatalogObject
    }
}
```

#### Share

```javascript
{
    interaction: {
        name: SalesforceInteractions.CatalogObjectInteractionName.ShareCatalogObject,
        catalogObject: CatalogObject
    }
}
```

#### Comment

```javascript
{
    interaction: {
        name: SalesforceInteractions.CatalogObjectInteractionName.CommentCatalogObject,
        catalogObject: CatalogObject
    }
}
```

#### Favorite

```javascript
{
    interaction: {
        name: SalesforceInteractions.CatalogObjectInteractionName.FavoriteCatalogObject,
        catalogObject: CatalogObject
    }
}
```

#### Quick View Catalog Object

```javascript
{
    interaction: {
        name: SalesforceInteractions.CatalogObjectInteractionName.QuickViewCatalogObject,
        catalogObject: CatalogObject
    }
}
```

### CartInteraction

#### Add To Cart

```javascript
{
    interaction: {
        name: SalesforceInteractions.CartInteractionName.AddToCart,
        lineItem: LineItem
    }
}
```

#### Replace Cart

```javascript
{
    interaction: {
        name: SalesforceInteractions.CartInteractionName.ReplaceCart,
        lineItems: LineItem[]
    }
}
```

#### Remove From Cart

```javascript
{
interaction: {
    name: SalesforceInteractions.CartInteractionName.RemoveFromCart,
    lineItem: LineItem
  }
}
```

### OrderInteraction

**note:** Personalization accepts OrderInteractions other than the Purchase OrderInteraction but only the Purchase OrderInteraction updates a user's order in Personalization.

#### Purchase

```javascript
{
    interaction: {
        name: SalesforceInteractions.OrderInteractionName.Purchase,
        order: Order
    }
}
```

#### Preorder

```javascript
{
    interaction: {
        name: SalesforceInteractions.OrderInteractionName.Preorder,
        order: Order
    }
}
```

#### Cancel

```javascript
{
    interaction: {
        name: SalesforceInteractions.OrderInteractionName.Cancel,
        order: Order
    }
}
```

#### Ship

```javascript
{
    interaction: {
        name: SalesforceInteractions.OrderInteractionName.Ship,
        order: Order
    }
}
```

#### Deliver

```javascript
{
    interaction: {
        name: SalesforceInteractions.OrderInteractionName.Deliver,
        order: Order
    }
}
```

#### Return

```javascript
{
    interaction: {
        name: SalesforceInteractions.OrderInteractionName.Return,
        order: Order
    }
}
```

#### Exchange

```javascript
{
    interaction: {
        name: SalesforceInteractions.OrderInteractionName.Exchange,
        order: Order
    }
}
```

### Other Interactions

#### Stop Quick View Catalog Object

```javascript
{
    interaction: {
        name: SalesforceInteractions.mcis.CatalogObjectInteractionName.StopQuickViewCatalogObject,
    }
}
```

## Best Practices For Using Interactions

When using interactions, it’s important to keep the following best practices in mind:

- Only track interactions if they're necessary for personalization and targeting. Think about the personalization use cases you wish to execute and only map the interactions required for those specific use cases.
- Map no more than a few thousand unique interactions per dataset. Mapping any more leads to challenges when using the Personalization UI, including difficulties in selecting interactions from dropdown menus and slower report generation.
- Ensure interaction names have values you can reuse across users and sessions.
- When defining interaction names, avoid dynamically populating them to prevent inflated names with unexpected prefixes and suffixes.
- If you dynamically populate interaction names, ensure they stay consistent across sessions for any user.
- Refrain from automatically sending all events from other site analytics tools to Personalization, as it can result in a higher volume of events than necessary for personalization.
- Incorporating dynamic user information in interaction names can cause issues and must be avoided whenever possible.

<!-- document id=2f84c463cc7b1eab783016d57f13c4821850fd3d75f707ffd03c69257dbb3e13 url=/developer/current/en-us/personalization/personalization/guides/event-api/event-options-salesforceinteractions.md -->

# Interaction Event Options in the SalesforceInteractions Namespace

The following code sample details the event options available in the `SalesforceInteractions` namespace in the Personalization module of the Salesforce Interactions SDK.

```javascript
interface ActionEvent<InteractionType extends Interaction> {
    interaction: InteractionType;
    debug?: boolean;
    flags?: boolean;
    user?: User;
    account?: Account;
    source?: Source;
    consents?: Consent[];
    explain?: boolean; // If true, then return additional information in the response about why campaigns did or did not render. Requires authentication.
    pageView?: boolean; // If true, indicates that the event was triggered from a page load.
    time?: number; // The date and time of the event (in milliseconds) elapsed since the UNIX epoch. This field is optional and will be auto-populated with the current time if null.
    performance?: PerformanceMetrics;
    campaignStats?: CampaignStat[],
}
```

## The interaction Object

The `interaction` object has the following structure.

```javascript
{
    interaction: Interaction,
    ...
}
```

### Interaction

You can use the `Interaction` field to capture user engagement data. The `Interaction` field has the following structure.

```javascript
interface Interaction {
  name: string;
}
```

### CatalogObjectInteraction

This type of `Interaction` is used to capture engagement data about catalog objects.

```javascript
interface CatalogObjectInteraction extends Interaction {
    name: CatalogObjectInteractionName;
    catalogObject: CatalogObject;
}

interface CatalogObject {
    type: string;
    id: string;
    attributes?: { [key: string]: any };
    relatedCatalogObjects?: { [catalogObjectType: string]: string[] };
}

enum CatalogObjectInteractionName {
    ViewCatalogObject = 'View Catalog Object',
    ViewCatalogObjectDetail = 'View Catalog Object Detail',
    QuickViewCatalogObject = 'Quick View Catalog Object',
    ShareCatalogObject = 'Share Catalog Object',
    ReviewCatalogObject = 'Review Catalog Object', // This Interaction is not supported in Marketing Cloud Personalization
    CommentCatalogObject = 'Comment Catalog Object',
    FavoriteCatalogObject = 'Favorite Catalog Object'
}

```

#### The location Object

You can use the `location` object to send location data on a `catalogObject` via the Event API or using the Sitemap. The following is an example of how to structure a `catalogObject` to include location data.

```json
"catalogObject": {
    "id": "test_product_one",
    "type": "Product",
    "attributes": {
        "location": {
            "longlat": [-71.1502415, 42.3571222],
            "city": "Boston",
            "stateProvinceCode": "MA",
            "postalCode": "02134",
            "countryNumericCode": "840"
        }
    }
}
```

The following examples depict sending data for locations outside the US.

```json
"catalogObject": {
    "id": "test_product_two",
    "type": "Product",
    "attributes": {
        "location": {
            "longlat": [144.963058, -37.813629],
            "city": "Melbourne",
            "stateProvinceCode": "VIC",
            "postalCode": "3005",
            "countryNumericCode": "036"
        }
    }
}
```

```json
"catalogObject": {
    "id": "test_product_three",
    "type": "Product",
    "attributes": {
        "location": {
            "longlat": [139.691711, 35.689487],
            "city": "Tokyo",
            "stateProvinceCode": "13",
            "postalCode": "100-0004",
            "countryNumericCode": "392"
        }
    }
}
```

### CartInteraction

This type of `Interaction` is used to capture engagement data about the contents of a user's cart.

```javascript
enum CartInteractionName {
    AddToCart = 'Add To Cart',
    RemoveFromCart = 'Remove From Cart',
    ReplaceCart = 'Replace Cart'
}

interface CartInteraction extends Interaction {
    name: CartInteractionName;
}

interface AddToCartInteraction extends CartInteraction {
    name: CartInteractionName.AddToCart;
    lineItem: LineItem;
}

interface RemoveFromCartInteraction extends CartInteraction {
    name: CartInteractionName.RemoveFromCart;
    lineItem: LineItem;
}

interface ReplaceCartInteraction extends CartInteraction {
    name: CartInteractionName.ReplaceCart;
    lineItems: LineItem[];
}

```

**note:** At this time, the [Personalization Event Stream report](https://developer.salesforce.com/docs/marketing/personalization/web-integration/sitemap-event-validation.md#event-validation-using-the-event-stream-report) doesn't display `ReplaceCart` interactions. Instead, if you use `SalesforceInteractions.CartInteractionName.ReplaceCart`, the associated `ReplaceCart` interactions appear in the Event Stream report as "View Cart" interactions.

### OrderInteraction

This type of `Interaction` is used to capture engagement data about the items in a user's order. Only the `PurchaseOrderInteraction` affects and updates a user's current order.

```javascript
interface Order {
    id: string;
    lineItems?: LineItem[];
    totalValue?: number;
    currency?: string;
    attributes?: { [key: string]: any };
}

enum OrderInteractionName {
    Purchase = 'Purchase',
    Preorder = 'Preorder',
    Cancel = 'Cancel',
    Ship = 'Ship',
    Deliver = 'Deliver',
    Return = 'Return',
    Exchange = 'Exchange'
}

interface OrderInteraction extends Interaction {
    name: OrderInteractionName;
    order: Order;
}

interface PurchaseOrderInteraction extends OrderInteraction {
    name: OrderInteractionName.Purchase;
    order: Order;
}

interface PreorderOrderInteraction extends OrderInteraction {
    name: OrderInteractionName.Preorder;
    order: Order
}

interface CancelOrderInteraction extends OrderInteraction {
    name: OrderInteractionName.Cancel;
    order: Order
}

interface ShipOrderInteraction extends OrderInteraction {
    name: OrderInteractionName.Ship;
    order: Order
}

interface DeliverOrderInteraction extends OrderInteraction {
    name: OrderInteractionName.Deliver;
    order: Order
}

interface ReturnOrderInteraction extends OrderInteraction {
    name: OrderInteractionName.Return;
    order: Order
}

interface ExchangeOrderInteraction extends OrderInteraction {
    name: OrderInteractionName.Exchange;
    order: Order
}

```

### Line Item

A `LineItem` represents a single item in a cart or transaction. A `LineItem` object has the following structure.

```javascript
interface LineItem {
  catalogObjectType: string;
  catalogObjectId: string;
  quantity: number;
  price: number;
  currency?: string;
  attributes?: { [key: string]: any }; // Include sku under attributes
}
```

The following table describes the properties that a `LineItem` object accepts.

| Property            | Value Type                                      | Description                                                                                                                                                                              |
| ------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `catalogObjectType` | String                                          | The type representing the catalog object.                                                                                                                                                |
| `catalogObjectId`   | String                                          | A unique ID representing the catalog object.                                                                                                                                             |
| `quantity`          | Number                                          | The number of catalog objects in the line item.                                                                                                                                          |
| `price`             | Number                                          | The price of the catalog object in the line item. **Important:** `price` is mandatory only when using `LineItem` in a purchase or cart interaction, and optional for other interactions. |
| `currency`          | String                                          | Optional. Currency code of purchase. If currency is unspecified or `null`, it defaults to the dataset's configured currency.                                                             |
| `attributes`        | `{[key: string]: string \| number \| boolean }` | Optional. Key-value pairs that are stored as metadata on the `LineItem`. You can include `sku` within `attributes`.                                                                      |

The following is an example of a line item used within an `AddToCart` interaction.

```javascript
// Example: Without SKU
{
	interaction: {
		name: "Add To Cart",
		lineItem: {
			catalogObjectType: "Product",
			catalogObjectId: "product-1",
			quantity: 1,
			price: 9.99,
			currency: "USD",
			attributes: {
				giftWrapping: 1
			}
		}
	}
}

// Example: With SKU
{
	interaction: {
		name: "Add To Cart",
		lineItem: {
			catalogObjectType: "Product",
			quantity: 1,
			price: 9.99,
			currency: "USD",
			attributes: {
				sku: {
					id: "sku12345"
				}
			}
		}
	}
}
```

**note:** At this time, the Personalization Event Stream doesn't display `price` for `AddToCart` events.

## The consent Object

The `consent` field accepts an array of consent objects for the user. The following table describes the various properties available in the `consent` object.

| Property   | Value Type | Description                                                  |
| ---------- | ---------- | ------------------------------------------------------------ |
| `purpose`  | String     | The purpose for the consent. For example, `Personalization`. |
| `provider` | String     | The consent provider                                         |
| `status`   | String     | The consent status. For example, `OptIn` or `OptOut`         |

## The debug Object

The `debug` object contains fields that help investigate issues that could arise when developing campaigns.

The following table describes the properties available in the `debug` object.

| Property       | Value Type | Description                                                                                                                                                                                                                                                                       |
| -------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `testMessages` | String     | A comma-separated list of campaign experience IDs to be forced to return in the event, ignoring rules that otherwise prevent the campaign from returning. Alternatively, you can use the string value `true` to return all campaigns in testing mode but all rules are respected. |

## The flags Object

The `flags` object contains properties that alter default event processing. By default, all flags are `false` if not present on the event.

The following table describes the various properties available in the `flags` object.

| Property         | Value Type | Description                                                                                                                                                      |
| ---------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `noCampaigns`    | Boolean    | If `true`, don’t return campaigns in the response.                                                                                                               |
| `nonInteractive` | Boolean    | If `true`, a visit isn’t created (or updated) for the given user in the event. Additionally, no visit referrer nor originating referrer is created for the user. |

## Source

The `Source` object contains properties that help describe where an event is coming from. This object has the following structure.

```javascript
interface Source {
    channel?: string,
    application?: string,
    pageType?: string,
    url?: string,
    urlReferrer?: string,
    locale?: string,
    contentZones?: string,
    configVersion?: number,
    userAgent?: string,
    clientIp?: string,
    operatingSystem?: string // only applicable for mobile events
    operatingSystemVersion?: string // only applicable for mobile events
    device?: string // only applicable for mobile events
    surveyId?: string // set through the Survey Gear
    surveyStartTime?: string // set through the Survey Gear
}
```

The following table describes the various properties available in the `Source` object.

| Property                 | Value Type | Description                                                                                                                                                                            |
| ------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `channel`                | String     | The originating source of the event (For example, `Web`, `MobileApp`, `CallCenter`).                                                                                                   |
| `application`            | String     | The originating application level source of the event (For example, `ReactApp`, `3rdParty`, `ReactNative`)                                                                             |
| `pageType`               | String     | The type of page from which you’re sending the event (For example, `PDP`, `Blog`, `Pricing`).                                                                                          |
| `url`                    | String     | The URL of the page from which you’re sending the event.                                                                                                                               |
| `urlReferrer`            | String     | The previous URL visited by the user. `urlReferrer` is populated from `document.referrer` by default on the web. It can be overwritten in the sitemap to any other value if necessary. |
| `locale`                 | String     | The locale of the current page, as defined by ISO 639 alpha-2 language codes and ISO 3166 alpha-2 country codes (For example, `en_US`, `de_DE`).                                       |
| `contentZones`           | `string[]` | An array of content zones on the current page.                                                                                                                                         |
| `configVersion`          | Number     | Version number of the configuration for the SDK.                                                                                                                                       |
| `userAgent`              | String     | The user agent for the event. `userAgent` is populated automatically but can be overwritten if necessary                                                                               |
| `clientIp`               | String     | The IP Address sending the event. `clientIp` is populated automatically but can be overwritten if necessary                                                                            |
| `operatingSystem`        | String     | Only applicable for mobile events.                                                                                                                                                     |
| `operatingSystemVersion` | String     | Only applicable for mobile events.                                                                                                                                                     |
| `device`                 | String     | Only applicable for mobile events.                                                                                                                                                     |
| `surveyId`               | String     | The ID of the survey being submitted. Set automatically for events sent through the Survey Gear                                                                                        |
| `surveyStartTime`        | String     | The start time of the survey being submitted. Set automatically for events sent through the Survey Gear                                                                                |

## The User Object

The `User` object describes the user associated with an event.

```javascript
interface User {
  anonymousId?: string;
  identities?: {
    [key: string]: string,
  };
  attributes?: {
    [key: string]: string | number | boolean,
  };
  profileObjects?: {
    [profileObjectType: string]: ProfileObject[],
  };
}
```

The following table describes the various properties available in the `user` object.

| Property         | Value Type                                         | Description                                                                                                                                                                 |
| ---------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `anonymousId`    | String                                             | The ID of an anonymous user.                                                                                                                                                |
| `identities`     | `[key: string]: string`                            | Key-value pairs that are stored as identity information of a user.                                                                                                          |
| `encryptedId`    | String                                             | The encrypted ID returned from an event that contains the ID field. Encrypted IDs are returned in the response to events that provide identities.                           |
| `attributes`     | `{ [key: string]: string \| number \| boolean }`   | Key-value pairs that are stored as metadata on the user. These attributes must be defined in the platform.                                                                  |
| `profileObjects` | `{ [profileObjectType: string]: ProfileObject[] }` | Key-value pairs of profile objects that are stored as metadata on the user. Profile objects, their attributes, and related catalog objects must be defined in the platform. |

### Profile Object

You can use the `profileObjects` field to send new or update existing profile objects via the Event API or using the Web SDK. You can send multiple profile objects of one type or multiple types in a single event.

```javascript
interface ProfileObject {
  id: string;
  relatedCatalogObjects?: { [catalogObjectType: string]: string[] };
  attributes?: { [key: string]: string | number | boolean };
}
```

**note:** To enable **Strict Profile Object Security**, log on to the Personalization UI and navigate to **Settings** > **Catalog and Profile Objects** > **User Profile Object Settings**. Enabling this setting restricts profile object updates to authenticated event sources such as ETL and Event API calls that use `channel: Server` and the `/authevent` endpoint. After it’s enabled, updates to profile objects from unauthenticated channels such as `Web` are ignored.

**important:** - If an event causes a user to exceed 100 profile objects of a specific type, the 100 most recent objects are retained based on their creation date.
- You can’t selectively update the fields of a profile object. You can only replace each instance of a profile object entirely. If you're updating an existing profile object, fields in the incoming event entirely replace the user's existing profile object fields.
- You can't entirely replace a set of profile objects of a given type with another set or an empty set. For example, an event with `profileObjects: { Lease: [] }` doesn't clear out all `Leases` on that given user.
- You can only create new or replace existing profile objects with Event API calls and not remove them.

The following table describes the properties that a `ProfileObject` accepts.

| Property                | Value Type                                       | Description                                                                                                                           |
| ----------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | String                                           | The ID of a Profile Object.                                                                                                           |
| `relatedCatalogObjects` | `{ [catalogObjectType: string]: string[] }`      | Related catalog objects key-value pairs. These related catalog objects must be defined in the platform.                               |
| `attributes`            | `{ [key: string]: string \| number \| boolean }` | Attribute key-value pairs that are stored as metadata on the profile object record. These attributes must be defined in the platform. |

The following example depicts sending a single “Lease” profile object record with attributes and related catalog objects.

```json
"profileObjects": {
    "Lease": [
        {
            "id": "55X1V44",
            "relatedCatalogObjects": {
                "Color": ["red", "blue"],
                "Make": ["car company"]
            },
            "attributes": {
                "duration": 365,
                "startDate": 1641502977863
            }
        }
    ]
}
```

## The Account Object

The `Account` object describes the account associated with an event.

```javascript
interface Account {
  id?: string;
  attributes?: {
    [key: string]: string | number | boolean,
  };
}
```

The following table describes the various properties available in the `account` object.

| Property     | Value Type                                       | Description                                                                                                   |
| ------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `id`         | String                                           | The ID of an account.                                                                                         |
| `attributes` | `{ [key: string]: string \| number \| boolean }` | Key-value pairs that are stored as metadata on the account. These attributes must be defined in the platform. |

## The PerformanceMetrics Object

The `PerformanceMetrics` object has properties that measure loading, parsing, and network performance.

```javascript
interface Performance {
  sdkLoadTimeMs?: number;
  sdkParseTimeMs?: number;
  pageLoadTimeMs?: number;
  networkTimeMs?: number;
}
```

The following table describes the various properties available in the `PerformanceMetrics` object.

| Property         | Value Type | Description                                                                    |
| ---------------- | ---------- | ------------------------------------------------------------------------------ |
| `sdkLoadTimeMs`  | Number     | (Web SDK) Time, in milliseconds, for the network to load the web SDK.          |
| `sdkParseTimeMs` | Number     | (Web SDK) Time, in milliseconds, for the beacon to be parsed during page load. |
| `pageLoadTimeMs` | Number     | (Web SDK) Time, in milliseconds, for the DOM to load.                          |
| `networkTimeMs`  | Number     | (Web SDK) Time, in milliseconds, for the previous request to return.           |

## The campaignStats Object

You can use the `campaignStats` object to track campaign statistics for an associated event.

For more information on sending campaign statistics on the web, refer to the [Campaign Stats Tracking](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/templates/campaign-stats-tracking.md) documentation.

The `campaignStats` object has the following structure.

```javascript
{
    ...
    {
        campaignStats: CampaignStat[]
    }
    ...
}
```

### The CampaignStat Object

The `CampaignStat` object has the following structure.

```javascript
{
    experienceId: string,
    stat: "Impression" | "Click" | "Dismissal",
    control: boolean,
    catalog: {
        <ItemType>: string[]
    }
}
```

The following table describes the properties a `CampaignStat` object accepts.

| Property       | Value Type                               | Description                                                                                                    |
| -------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `experienceId` | String                                   | The experience ID of the campaign on which the given statistic is being tracked                                |
| `stat`         | `"Impression" \| "Click" \| "Dismissal"` | The type of statistic being tracked.                                                                           |
| `control`      | Boolean                                  | If `true`, the statistic is tracked for the control group of the given experience.                             |
| `catalog`      | `{ <ItemType>: string[] }`               | A mapping of catalog item types to a list of corresponding item IDs on which to attribute the given statistic. |

The following is an example of a mapping of catalog item types.

```javascript
...
catalog: {
    Product: ["product1", "product2"]
}
...
```

<!-- document id=ed62ad2a56e8eb952364194cd94a23da0613797ab9917a2356f523b2513573ae url=/developer/current/en-us/personalization/personalization/guides/web-integration/item-actions.md -->

# Item Actions

The `itemAction` property of the Salesforce Interactions SDK is used to identify actions users take on catalog items such as "Purchase" or "AddToCart".

Item actions are a separate event property from regular actions (`action`). Item actions contain reserved action names used by Marketing Cloud Personalization to determine how to handle event data. Personalization automatically inserts the appropriate `itemAction` value when sending events containing catalog data originating from matching a `pageType` mapped in the Sitemap code. Therefore, avoid manually mapping the `itemAction` property in your `global` or `pageType` configurations, except in the following scenarios.

When mapping pages with `cart` or `order`, you must specify `itemAction` in your `pageType` configuration. Typically the `cart` object is mapped only on the cart page itself with the `itemAction` value of "View Cart" (`Evergage.ItemAction.ViewCart`). Similarly, `order` is only mapped on the order confirmation page with the `itemAction` value of "Purchase" (`Evergage.ItemAction.Purchase`). If no `lineItem` is provided with the Purchase ItemAction, the SDK defaults to using the current state of the cart as line items.

**important:** The Item Actions documented in this article are available exclusively in the `Evergage` namespace. In the `SalesforceInteractions` namespace, Interactions replace Item Actions. For more information, refer to the [Interaction Definitions](https://developer.salesforce.com/docs/marketing/personalization/guide/interaction-definitions.md) documentation.

## Actions

The `action` property is also used to track user interactions but isn’t specific to actions carried out on catalog items. The purpose of `action` is to provide a high-level overview of user behavior and to help identify trends or patterns in how users interact with a website or application. For example, you can use actions to track when a user views the home page or clicks a call to action.

You can also use actions for the following purposes:

- Segmentation: You can use actions as criteria to create user or audience segments. You can then target these segments to deliver personalized experiences, offers, or content based on their actions.
- Campaigns: By using actions for campaign targeting, you can qualify users who have either performed or not performed a specific set of actions.
- Actions Report: The Actions Report provides insights into user actions and user behavior over time within a given dataset, allowing marketers to identify key activities that are valuable for campaign targeting.
- Funnels: You can also use actions to track user progression through funnels. By mapping actions to each funnel step, you can track and analyze user behavior and identify steps where users drop off or encounter obstacles. Such insight can help optimize user journeys and improve conversion rates.

### Best Practices For Using Actions

When using actions, it’s important to keep the following in mind:

- Only track actions if they're necessary for personalization and targeting. Think about the personalization use cases you wish to execute and only map the actions required for those specific use cases.
- Map no more than a few thousand unique actions per dataset. Mapping any more leads to challenges when using the Personalization UI, including difficulties in selecting actions from dropdown menus and slower report generation.
- Ensure action names have values you can reuse across users and sessions.
- When defining action names, avoid dynamically populating them to prevent inflating names with unexpected prefixes and suffixes.
- If you dynamically populate action names, ensure they stay consistent across sessions for any user.
- Refrain from automatically sending all events from other site analytics tools to Personalization, as it can result in a higher volume of events than necessary for personalization.
- Incorporating dynamic user information in action names can cause issues and must be avoided whenever possible.

## Item Actions in the Event API

The item action property value must be manually set only when sending events to the Personalization platform using the Event API. Only the reserved item action values within `Evergage.ItemAction` can be used. Within the context of the Sitemap, the Event API is used to send an event independently of the page matching event using `Evergage.sendEvent()`.

An example of an event sent using the API within the Sitemap can be found in our [Example ecommerce Sitemap](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps/ecommerce.md) within the `"product_detail"` pageType configuration. The following code sample includes the relevant code block. In this example, a listener has been mapped containing an `AddToCart` event that fires when the user clicks the DOM element referenced by the provided selector, `".add-to-cart"`.

```javascript
listeners: [
    Evergage.listener("click", ".add-to-cart", () => {
        const lineItem = Evergage.util.buildLineItemFromPageState("select[id*=quantity]");
        lineItem.sku = { _id: Evergage.cashDom(".product-detail[data-pid]").attr("data-pid")};
        Evergage.sendEvent({
            itemAction: Evergage.ItemAction.AddToCart,
            cart: {
                singleLine: {
                    Product: lineItem
                }
            }
        });
    }),
],
```

## Reserved Item Action Values

The possible values for item action are all contained within the `Evergage.ItemAction` object. Be sure to reference all values assigned to the `itemAction` property from the `Evergage.ItemAction` object in the same way as the `AddToCart` event detailed in the previous section.

## Special Item Actions

- `Quick View Item` - Similar to `View Item` but stops the timer for the "background" item and starts a timer for the "foreground" item.
- `Stop Quick View Item` - Stops the timer initiated by the "Quick View Item" item action for the "foreground" item and restarts the timer for the "background" item.

You can use the `Quick View Item` and `Stop Quick View Item` item actions to accurately track view time in cases where a user "views" an item while already viewing a different item. An ecommerce category page that allows users to view individual products in a window can take advantage of these item actions. In the following example, the "background" item is the category and the "foreground" item is the product. A new page load stops both timers.

```javascript
config.pageTypes.push({
  name: "Category",
  action: "View Category",
  isMatch: () => {
    return (
      Evergage.cashDom(".page[data-action='Search-Show']").length > 0 &&
      Evergage.cashDom(".breadcrumb").length > 0
    );
  },
  catalog: {
    Category: {
      _id: Evergage.resolvers.buildCategoryId(".breadcrumb .breadcrumb-item a", 1),
    },
  },
  listeners: [
    Evergage.listener("click", ".quickview", (e) => {
      const pid = Evergage.cashDom(e.target).attr("href").split("pid=")[1];
      if (!pid) {
        return;
      }
      Evergage.sendEvent({
        action: "Category Page Quick View",
        itemAction: Evergage.ItemAction.QuickViewItem,
        catalog: {
          Product: {
            _id: pid,
          },
        },
      });
    }),
    Evergage.listener("click", "body", (e) => {
      if (Evergage.cashDom(e.target).closest("button[data-dismiss='modal']").length > 0) {
        Evergage.sendEvent({
          action: "Close Quick View",
          itemAction: Evergage.ItemAction.StopQuickViewItem,
        });
      }
    }),
  ],
});
```

## Currently Supported Item Actions

While other Item Actions are present in the `Evergage.ItemAction` object, only the Item Actions documented here are currently supported. Unless otherwise indicated, the following definitions apply to both the page config and Event API.

Many item actions mentioned in the following definitions rely on events that contain line items. To learn more about the structure of the `lineItem` object, see the [LineItem](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.md#lineitem) documentation.

### View Item

```javascript
{
    itemAction: Evergage.ItemAction.ViewItem,
    catalog: {
        <ItemType>: {
            [key: string]: string | number | boolean | object
        }
    }
}
```

### View Item Detail

```javascript
{
    itemAction: Evergage.ItemAction.ViewItemDetail,
    catalog: {
        <ItemType>: {
            [key: string]: string | number | boolean | object
        }
    }
}
```

### View Item Out Of Stock

```javascript
{
    itemAction: Evergage.ItemAction.ViewItemOutOfStock,
    catalog: {
        Product: {
            [key: string]: string | number | boolean | object
        }
    }
}
```

### Quick View Item

```javascript
{
    itemAction: Evergage.ItemAction.QuickViewItem,
    catalog: {
        <ItemType>: {
            [key: string]: string | number | boolean | object
        }
    }
}
```

### Stop Quick View Item

```javascript
{
    itemAction: Evergage.ItemAction.StopQuickViewItem,
    catalog: {
        <ItemType>: {
            [key: string]: string | number | boolean | object
        }
    }
}
```

### View Category

```javascript
{
    itemAction: Evergage.ItemAction.ViewCategory,
    catalog: {
        Category: {
            [key: string]: string | number | boolean | object
        }
    }
}
```

### Add To Cart

When using this specific action, only one item is updated at a time. A single `AddToCart` event doesn’t accept an array of items. If you want to add multiple items to the cart, the items must be sent in multiple events.

```javascript
{
    itemAction: Evergage.ItemAction.AddToCart,
    cart: {
        singleLine: {
            Product: LineItem
        }
    }
}
```

### View Cart

A `viewCart` event fully updates the items that a user has in their cart. For example, sending a `viewCart` event via the Event API overwrites any items currently saved in the user's cart.

**Sitemap PageType Definition**

```javascript
{
    itemAction: Evergage.ItemAction.ViewCart,
    catalog: {
        Product: {
            lineItems: {
                _id: string[],
                price: number[],
                quantity: number[]
            }
        }
    }
}
```

**Event API**

```javascript
{
    itemAction: 'View Cart',
    cart: {
        complete: {
            Product: LineItem[]
        }
    }
}
```

### Purchase

**Sitemap PageType Definition**

```javascript
{
	itemAction: Evergage.ItemAction.Purchase,
	catalog: {
		Product: {
			orderId: string,
			totalValue ? : number,
			currency ? : string,
			lineItems: {
				_id: string[] | () => string[],
				price: number[] | () => number[],
				quantity: number[] | () => number[].
			}
		}
	}
}
```

**Event API**

```javascript
{
    itemAction: 'Purchase',
    order: {
        Product: {
                orderId: string,
                totalValue?: number,
                currency?: string,
                lineItems: LineItem[]
        }
    }
}
```

### Share

```javascript
{
    itemAction: Evergage.ItemAction.Share,
    catalog: {
        <ItemType>: {
            [key: string]: string | number | boolean | object
        }
    }
}
```

### Comment

```javascript
{
    itemAction: Evergage.ItemAction.Comment,
    catalog: {
        <ItemType>: {
            [key: string]: string | number | boolean | object
        }
    }
}
```

### Favorite

```javascript
{
    itemAction: Evergage.ItemAction.Favorite,
    catalog: {
        <ItemType>: {
            [key: string]: string | number | boolean | object
        }
    }
}
```

### Update Line Item

When using this specific action, only one item is updated at a time. A single `UpdateLineItem` event doesn’t accept an array of items. If you want to update multiple cart items, you must send in multiple events.

```javascript
{
    itemAction: Evergage.ItemAction.UpdateLineItem,
    cart: {
        singleLine: {
            Product: LineItem
        }
    }
}
```

### Remove From Cart

The `RemoveFromCart` item action only removes one line item from the cart at a time. A single `RemoveFromCart` event doesn't accept an array of line items. To remove multiple cart items, you must send in multiple events.

```javascript
{
    itemAction: Evergage.ItemAction.RemoveFromCart,
    cart: {
        singleLine: {
            Product: LineItem
        }
    }
}
```

The following example depicts how you can use the `RemoveFromCart` item action to remove a line item from a shopping cart.

```javascript
{
    "itemAction": "Evergage.ItemAction.RemoveFromCart",
    "cart": {
        "singleLine": {
            "Product": {
                    "_id": "123",
                    "price": 10.99,
                    "quantity": 3
                }
        }
    }
}
```

<!-- document id=19a5f9c93027d741723db7324e01f2003fe14e78251a4530fcc881a40a269a9a url=/developer/current/en-us/personalization/personalization/guides/web-integration/managing-cors-with-sdk-launcher.md -->

# Manage CORS with the Salesforce Interactions SDK Launcher

The Salesforce Interactions SDK Launcher is a Google Chrome extension that supports launching the Marketing Cloud Personalization Visual Editor on any domain. You can install this extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/salesforce-interactions-s/mhmpepeohaddbhkhecaldflljggicedf).

**warning:** If you have the legacy Evergage Visual Editor Chrome extension installed, you must **disable** it for the Salesforce Interactions SDK Launcher to work correctly.

## Required HTTP Header Configuration

### Content-Security-Policy

- The value of the [`default-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/default-src) directive must include `'https://cdn.evergage.com'`.
- If you're using [`media-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/media-src), [`script-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src), [`img-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/img-src), or [`style-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src) directives in place of [`default-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/default-src), then each directive must include `'https://cdn.evergage.com'` in their values.
- If the policy includes the [`frame-ancestors`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors) directive, the value must include `'self'`. (Generally, if this directive is in use, its value is set to `none`, which prevents the Visual Editor from framing in your page.)

### X-Frame-Options

`X-Frame-Options` must be set to `SAMEORIGIN` which allows the page to be displayed within an `<iframe>`, provided that the parent/frame domains are of the same origin.

**note:** Some pages utilize other methods of blocking the loading of unknown resources. If your page restricts the loading of scripts or assets to specific domains in different ways, you must allowlist `https://cdn.evergage.com`.

## Chrome Settings

To ensure that the Salesforce Interactions SDK Launcher extension works correctly, check and configure the following extension and browser settings.

- Access `chrome://extensions` on Google Chrome
  - Select **Details** on the **Salesforce Interactions SDK Launcher** tile
  - Set **Set Access** to **On all site**
- Access `chrome://settings/cookies` on Google Chrome
  - Disable **Block third-party cookies**

## See Also

- _Salesforce Developers_: [Content Security Policies and Personalization JavaScript Beacon Directives](https://developer.salesforce.com/docs/marketing/personalization/guide/content-security-policies-javascript-beacon-directives.md)
- _External Link_: [MDN Web Docs: `Content-Security-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)

<!-- document id=0668ed52713b07b199a2776f1f754a8658f089047a39db22ad1fa9d0b4a525aa url=/developer/current/en-us/personalization/personalization/guides/data-analytics/data-analytics.md -->

# Marketing Cloud Personalization Data Analytics

Through its normal operations, Marketing Cloud Personalization tracks and measures customer and prospect engagement across a company’s many channels at both the individual and business account levels. The data tracked by Personalization includes digital interactions, active time spent, preferences, intent, purchases, referring source, browser, geolocation, survey responses, weather, and other indicators or measures of engagement and behavior.

## Personalization Data Warehouse

Personalization supports analytics on the data it tracks through Data Warehouse. Using Business Intelligence (BI) tools, business data analysts and data scientists can analyze and report on data without impacting the performance of Personalization or the company website. Data analytics capabilities on the Personalization Data Warehouse enable companies to better understand their customers, evaluate their campaigns, personalize content, create content strategies, develop better products, and more.

**note:** The Data Warehouse is available only to customers who have already purchased the Marketing Cloud Personalization - Data Warehouse add-on product.

## Data Warehouse Specifications

The articles in this section provide the specifications for the Personalization Data Warehouse, including:

- [Data Warehouse Physical Data Model](https://developer.salesforce.com/docs/marketing/personalization/guide/data-warehouse.md): Physical data model of the data warehouse.
- [Data Dictionary](https://developer.salesforce.com/docs/marketing/personalization/guide/data-dictionary.md): Data specifications for the tables in the data warehouse.
- [Scratch Schema](https://developer.salesforce.com/docs/marketing/personalization/guide/scratch-schema.md): Schema specifications for scratch tables used for machine learning, data analysis, investigation, and reporting.

<!-- document id=d6306f356e4911e9c650e66060c430fe5a9f11157262b4a175f93303682aa90c url=/developer/current/en-us/personalization/personalization/guides/event-api/event-api.md -->

# Marketing Cloud Personalization Event API

The Marketing Cloud Personalization Event API allows sources to send event data to the Personalization platform to be processed in the event pipeline, which then returns Campaigns that can be served to the end user. The Event API also allows for authenticated requests, returning internal Campaign data.

**important:** Don’t use the Event API to handle mobile application events. The Personalization [Mobile SDK](https://developer.salesforce.com/docs/marketing/personalization/mobile-integration.md) has separate functionality used for mobile app event processing, with built-in features that are currently unavailable through the Event API.

## Event Options and Schemas

The event schema used to structure event data in the Personalization platform depends on the Salesforce Interactions SDK namespace you use. For more information about the event schemas and available event options in each namespace, see:

- [Interaction Event Options in the `SalesforceInteractions` Namespace](https://developer.salesforce.com/docs/marketing/personalization/guide/event-options-salesforceinteractions.md)
- [Event Options in the `Evergage` Namespace](https://developer.salesforce.com/docs/marketing/personalization/guide/event-options-evergage.md)

## Event API Specifications

For information about standard HTTP methods and JSON-formatted objects that you can use in the Sitemap and other event sources to interact with the Personalization platform, see [Event API Requests](https://developer.salesforce.com/docs/marketing/personalization/guide/event-api-requests.md).

## See Also

- [_Salesforce Help_: TLS Trust and Marketing Cloud Personalization](https://help.salesforce.com/s/articleView?id=mktg.mc_pers_integration_tls_trust.htm)

<!-- document id=60a1398c48cc2fad67ac516b3c9f210fc7f64dc5c42d08bed6336b61ce19f751 url=/developer/current/en-us/personalization/personalization/guides/mobile-integration.md -->

# Marketing Cloud Personalization Mobile Integrations

Marketing Cloud Personalization [web templates](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-development/personalization-template-system.md) are based on responsive HTML and can support web campaigns that are displayed on mobile devices. However, these "standard" web templates cannot leverage all of the features and capabilities available to native mobile apps. For companies and developers who want Personalization to have access to native mobile app features and capabilities, Personalization provides an Apple iOS SDK and Android SDK for mobile app integration.

## Personalization Mobile SDKs

Personalization provides software development kits (SDKs) that developers can use to integrate Personalization with native iOS and native Android mobile applications. The Personalization mobile SDKs gather information about the user, device, and in-app behavior and send it to Personalization to build profiles, generate statistics, and feed machine learning. The SDKs also handle event responses containing personalization [campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_mobile_campaign.htm) for qualified mobile application users.

### Mobile SDK Developer Documentation

For complete instructions, SDK specifications, and requirements for mobile app developers, refer to the following documentation sites.

| SDK                                | Version                                                                                                                                 |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Personalization iOS Mobile SDK     | [v1.5.0 (latest)](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-ios-sdk/overview.html)     |
|                                    | [v1.4.2](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-ios-sdk/v1.4.2/overview.html)       |
|                                    | [v1.4.1](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-ios-sdk/v1.4.1/overview.html)       |
|                                    | [v1.4.0](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-ios-sdk/v1.4.0/overview.html)       |
|                                    | [v1.3.3](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-ios-sdk/v1.3.3/overview.html)       |
|                                    | [v1.3.2](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-ios-sdk/v1.3.2/overview.html)       |
|                                    | [v1.3.1](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-ios-sdk/v1.3.1/overview.html)       |
|                                    | [v1.3.0](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-ios-sdk/v1.3.0/overview.html)       |
| Personalization Android Mobile SDK | [v1.5.1 (latest)](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-android-sdk/overview.html) |
|                                    | [v1.5.0](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-android-sdk/v1.5.0/overview.html)   |
|                                    | [v1.4.2](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-android-sdk/v1.4.2/overview.html)   |
|                                    | [v1.4.1](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-android-sdk/v1.4.1/overview.html)   |
|                                    | [v1.4.0](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-android-sdk/v1.4.0/overview.html)   |
|                                    | [v1.3.1](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-android-sdk/v1.3.1/overview.html)   |
|                                    | [v1.3.0](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-android-sdk/v1.3.0/overview.html)   |
|                                    | [v1.2.3](https://developer.salesforce.com/docs/marketing/personalization/references/personalization-android-sdk/v1.2.3/overview.html)   |

## See Also

- [_Salesforce Help_: Mobile Campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_mobile_campaign.htm)

<!-- document id=eb0cecf9df44573779d37401acc1dca95e2ed777fc1bc7175800fa1af051210f url=/developer/current/en-us/personalization/personalization/guides/campaign-development/advanced-use-case-apis/is-trends.md -->

# Marketing Cloud Personalization Trends

Marketing Cloud Personalization Trends (IS Trends) uses the power of social validation to increase conversions. Most consumers are overwhelmed by the product choices available to them and can find it challenging to confidently buy products online. Use the “wisdom of the crowd” to influence visitors on your site in real time and build confidence in products viewed by using view and purchase counters. These view and purchase counters drive both validation and urgency ultimately influencing conversions on your site.

**note:** By enabling this feature, you’re allowing Personalization to return catalog object purchase and view data via a public API.

## API Functionality

### What Does the API Do?

Given one or more catalog object IDs and a number of lookback minutes, the IS Trends API is designed to return the number of views and recent purchases for those catalog object IDs within that lookback period.

### How is the API Called?

Requests to the IS Trends API can be made to URL endpoints that adhere to the following basic structure.

```
https://<accountName>.<instance>.evergage.com/api/dataset/<dataset>/social/smartTrends/Product?itemIds=<string>&lookbackMins=<integer>
```

**note:** For your API requests to work correctly, your request URLs must include your Personalization account name and instance identifier.

The following table lists the required and optional request URL parameters included in the preceding example.

#### Request URL Parameters

| URL Parameter           | Required? | Description                                                                                                                                                                                                                                  |
| ----------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountName`           | Yes       | Your Personalization account name. You can retrieve it by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if your Gears URL is `demo.us-1.evergage.com`, then your account name is `demo`.               |
| `instance`              | Yes       | Your Personalization instance identifier. You can retrieve it by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if your Gears URL is `demo.us-1.evergage.com`, then your instance identifier is `us-1`. |
| `dataset`               | Yes       | The name or identifier of the Personalization dataset you’re sending data to.                                                                                                                                                                |
| `itemIds: string`       | Yes       | Provide either a singular item ID or a comma-separated list of item IDs.                                                                                                                                                                     |
| `lookbackMins: integer` | No        | An integer representing the number of minutes to be used for a lookback period. This value can’t exceed 2880 minutes (2 days).                                                                                                               |

#### Example Requests

Given parameters:

```
accountName = "example"
instance = "us-1"
dataset = "engage"
itemIds = "4100323" | "1010263,1050855,1031064,1050946"
lookbackMins = 120
```

- Single ID: `https://example.us-1.evergage.com/api/dataset/engage/social/smartTrends/Product?itemIds=4100323&lookbackMins=120`
- Multiple IDs: `https://example.us-1.evergage.com/api/dataset/engage/social/smartTrends/Product?itemIds=1010263,1050855,1031064,1050946&lookbackMins=120`

### What Data Can It Return?

Returns an object with keys representing the itemID(s). The value for these keys each have an object containing stats for `visitViews` and `purchases` within the lookback period provided in the request.

The stat values in the response reflect the stats that 's been tracked against _only the specific catalog objects_ within the lookback period, meaning that the stat values don’t account for views and/or purchases of the catalog object through a relationship to another catalog object. For instance, if a purchase is tracked for Product X and Category Y is related to it, a request to the IS Trends API with the `itemId` for Category Y results in a response with 0 `purchases`.

**note:** With the preceding note in mind, it is expected that the value for `purchases` is only greater than 0 when sending `itemIds` for the Product catalog object.

#### Example Responses

- Single ID: `{"4100323":{"visitViews":1,"purchases":0}}`
- Multiple IDs: `{"1050946":{"visitViews":0,"purchases":0},"1010263":{"visitViews":0,"purchases":0},"1050855":{"visitViews":0,"purchases":0},"1031064":{"visitViews":0,"purchases":0}}`

## Sample Template

Use one of the following links to download a ZIP file containing the sample IS Trends template for your SDK namespace.

- [`SalesforceInteractions` namespace](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/ISTrends-SalesforceInteractions.zip)
- [`Evergage` namespace](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/ISTrends-Evergage.zip)

While the default configuration of the example template is for Products, you can use it with other catalog types by making the following changes.

1. Change the value of `settings.id` to reference the desired Catalog Object type.
2. Change the URL string returned by `settings.url` to reference the desired Catalog Object type.

For example, if you’re customizing this template for Articles, you would make the following changes to the properties in `settings`.

```javascript
const settings = {
    ...
    id: (((SalesforceInteractions.mcis.getSitemapResult().currentPage || {}).interaction || {}).catalogObject || {})._id,
    ...
    url: () => `https://${settings.account}.evergage.com/api/dataset/${settings.dataset}/social/smartTrends/Article`
};
```

```javascript
const settings = {
    ...
    id: (((Evergage.getCurrentPage() || {}).catalog || {}).Article || {})._id,
    ...
    url: () => `https://${settings.account}.evergage.com/api/dataset/${settings.dataset}/social/smartTrends/Article`
};
```

### Full Sample Template Code

The sample IS Trends template consists of the following:

- Handlebars code
- CSS
- Server-side TypeScript code
- Client-side JavaScript code for the `SalesforceInteractions` and the `Evergage` SDK namespaces

```handlebars
{{!
    Template: IS Trends

    Requirements:
    1) Enable IS Trends for dataset (Settings > General Setup > Advanced Options > Enable IS Trends)
}}

<ul
  id="mcis-trends"
  class="mcis-trends"
  data-evg-campaign-id="{{campaign}}"
  data-evg-experience-id="{{experience}}"
  data-evg-user-group="{{userGroup}}"
>
</ul>
```

```css
#mcis-trends.mcis-trends {
  opacity: 0;
  padding: 0 15px;
  font-style: italic;
}

#mcis-trends.mcis-trends li {
  color: #ffa500;
  list-style-type: none;
}
```

```typescript
export class ISTrendsTemplate implements CampaignTemplateComponent {
  purchasesText: string;

  visitorsText: string;

  run(context: CampaignComponentContext) {
    return {
      purchasesText: this.purchasesText || "recently purchased",
      visitorsText: this.visitorsText || "visitors currently viewing",
    };
  }
}
```

```javascript
(function () {
  const ISTrends = (function () {
    const settings = {
      account: SalesforceInteractions.mcis.getConfig().account,
      dataset: SalesforceInteractions.mcis.getConfig().dataset,
      delay: 3000,
      id: (
        ((SalesforceInteractions.mcis.getSitemapResult().currentPage || {}).interaction || {})
          .catalogObject || {}
      ).id,
      lookbackMins: 2 * 60, // maximum 2 day
      minPurchases: 1,
      minViews: 1,
      reloadInterval: 30 * 1000,
      shouldCycle: true,
      stopLoadingAfter: 10 * 60 * 1000,
      url: () =>
        `https://${settings.account}.evergage.com/api/dataset/${settings.dataset}/social/smartTrends/Product`,
    };

    const global = {
      context: null,
      template: null,
    };

    const actions = {
      handleResults: (results) => {
        const { id, minPurchases, minViews } = settings;
        const { purchasesText, visitorsText } = global.context;

        const mcisTrendsContainer = SalesforceInteractions.cashDom("ul.mcis-trends");
        mcisTrendsContainer.css({ opacity: "0" });
        mcisTrendsContainer.empty();
        if (results[id].purchases >= minPurchases) {
          mcisTrendsContainer.append(`
                        <li id="evg-trend-minPurchases">
                            ${results[id].purchases} ${purchasesText}
                        </li>
                    `);
        }
        if (results[id].visitViews >= minViews) {
          mcisTrendsContainer.append(`
                        <li id="evg-trend-minViews">
                            ${results[id].visitViews} ${visitorsText}
                        </li>
                    `);
        }
        mcisTrendsContainer.css({ opacity: "1" });
      },
      loadTrends: () => {
        const { id, lookbackMins, url } = settings;
        const requestUrl = `${url()}?itemIds=${id}&lookbackMins=${lookbackMins}`;

        return fetch(requestUrl)
          .then((resp) => {
            return resp.json();
          })
          .then((data) => {
            return actions.handleResults(data);
          })
          .catch((err) => {
            console.warn(err);
          });
      },
    };

    return {
      init: function ({ context, template }) {
        const { reloadInterval, stopLoadingAfter } = settings;
        const { loadTrends } = actions;

        Object.assign(global, { context, template });
        loadTrends();
        const timerId = window.setInterval(loadTrends, reloadInterval);
        window.setTimeout(() => {
          settings.shouldCycle = false;
          clearInterval(timerId);
        }, stopLoadingAfter);
      },
    };
  })();

  /**
   * @function buildBindId
   * @param {Object} context
   * @description Create unique bind ID based on the campaign and experience IDs.
   */
  function buildBindId(context) {
    return `${context.campaign}:${context.experience}`;
  }

  function apply(context, template) {
    const contentZoneSelector = SalesforceInteractions.mcis.getContentZoneSelector(
      context.contentZone,
    );
    return SalesforceInteractions.DisplayUtils.bind(buildBindId(context))
      .pageElementLoaded(contentZoneSelector)
      .then((element) => {
        if (SalesforceInteractions.cashDom("#mcis-trends").length > 0) return;

        const html = template(context);
        SalesforceInteractions.cashDom(element).html(html);
        ISTrends.init({ context, template });
      });
  }

  function reset(context, template) {
    SalesforceInteractions.DisplayUtils.unbind(buildBindId(context));
    SalesforceInteractions.cashDom("#mcis-trends").remove();
  }

  function control(context) {
    const contentZoneSelector = SalesforceInteractions.mcis.getContentZoneSelector(
      context.contentZone,
    );
    return SalesforceInteractions.DisplayUtils.bind(buildBindId(context))
      .pageElementLoaded(contentZoneSelector)
      .then((element) => {
        SalesforceInteractions.cashDom(element).attr({
          "data-evg-campaign-id": context.campaign,
          "data-evg-experience-id": context.experience,
          "data-evg-user-group": context.userGroup,
        });
      });
  }

  registerTemplate({
    apply: apply,
    reset: reset,
    control: control,
  });
})();
```

```javascript
(function () {
  const ISTrends = (function () {
    const settings = {
      account: Evergage.getConfig().account,
      dataset: Evergage.getConfig().dataset,
      delay: 3000,
      id: (((Evergage.getCurrentPage() || {}).catalog || {}).Product || {})._id,
      lookbackMins: 2 * 60, // maximum 2 day
      minPurchases: 1,
      minViews: 1,
      reloadInterval: 30 * 1000,
      shouldCycle: true,
      stopLoadingAfter: 10 * 60 * 1000,
      url: () =>
        `https://${settings.account}.evergage.com/api/dataset/${settings.dataset}/social/smartTrends/Product`,
    };

    const global = {
      context: null,
      template: null,
    };

    const actions = {
      handleResults: (results) => {
        const { id, minPurchases, minViews } = settings;
        const { purchasesText, visitorsText } = global.context;

        const mcisTrendsContainer = Evergage.cashDom("ul.mcis-trends");
        mcisTrendsContainer.css({ opacity: "0" });
        mcisTrendsContainer.empty();
        if (results[id].purchases >= minPurchases) {
          mcisTrendsContainer.append(`
                        <li id="evg-trend-minPurchases">
                            ${results[id].purchases} ${purchasesText}
                        </li>
                    `);
        }
        if (results[id].visitViews >= minViews) {
          mcisTrendsContainer.append(`
                        <li id="evg-trend-minViews">
                            ${results[id].visitViews} ${visitorsText}
                        </li>
                    `);
        }
        mcisTrendsContainer.css({ opacity: "1" });
      },
      loadTrends: () => {
        const { id, lookbackMins, url } = settings;
        const requestUrl = `${url()}?itemIds=${id}&lookbackMins=${lookbackMins}`;

        return fetch(requestUrl)
          .then((resp) => {
            return resp.json();
          })
          .then((data) => {
            return actions.handleResults(data);
          })
          .catch((err) => {
            console.warn(err);
          });
      },
    };

    return {
      init: function ({ context, template }) {
        const { reloadInterval, stopLoadingAfter } = settings;
        const { loadTrends } = actions;

        Object.assign(global, { context, template });
        loadTrends();
        const timerId = window.setInterval(loadTrends, reloadInterval);
        window.setTimeout(() => {
          settings.shouldCycle = false;
          clearInterval(timerId);
        }, stopLoadingAfter);
      },
    };
  })();

  /**
   * @function buildBindId
   * @param {Object} context
   * @description Create unique bind ID based on the campaign and experience IDs.
   */
  function buildBindId(context) {
    return `${context.campaign}:${context.experience}`;
  }

  function apply(context, template) {
    const contentZoneSelector = Evergage.getContentZoneSelector(context.contentZone);
    return Evergage.DisplayUtils.bind(buildBindId(context))
      .pageElementLoaded(contentZoneSelector)
      .then((element) => {
        if (Evergage.cashDom("#mcis-trends").length > 0) return;

        const html = template(context);
        Evergage.cashDom(element).html(html);
        ISTrends.init({ context, template });
      });
  }

  function reset(context, template) {
    Evergage.DisplayUtils.unbind(buildBindId(context));
    Evergage.cashDom("#mcis-trends").remove();
  }

  function control(context) {
    const contentZoneSelector = Evergage.getContentZoneSelector(context.contentZone);
    return Evergage.DisplayUtils.bind(buildBindId(context))
      .pageElementLoaded(contentZoneSelector)
      .then((element) => {
        Evergage.cashDom(element).attr({
          "data-evg-campaign-id": context.campaign,
          "data-evg-experience-id": context.experience,
          "data-evg-user-group": context.userGroup,
        });
      });
  }

  registerTemplate({
    apply: apply,
    reset: reset,
    control: control,
  });
})();
```

<!-- document id=243cc53aa6399ac783bd9fc1d19f829f000816ed54c75c3c204f6ce5f6f26323 url=/developer/current/en-us/personalization/personalization/guides/web-integration.md -->

# Marketing Cloud Personalization Web Integration

## Salesforce Interactions SDK

The Salesforce Interactions SDK is an extensible data capture and collection framework that you can use to track website visitors’ profile data and different user interactions on your website and send that information to Salesforce. The SDK consists of a base SDK and product-specific modules for Marketing Cloud Personalization and Salesforce Data Cloud (formerly Customer Data Platform).

The SDK uses a unified event data model shared across the Personalization and Data Cloud SDK modules. This unified data model allows for capturing and integrating key business objects and user and behavioral data through event capture in a consistent format across Personalization and Data Cloud. The unified data model also enables you to use a single SDK to integrate with either Personalization, Data Cloud, or both together.

The following table describes the SDK modules to use depending on your use of Personalization and Data Cloud.

| Products Used                                                                                                     | Use                                                       | SDK Namespace            |
| ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------ |
| New customers using Personalization only                                                                          | Personalization module of the Salesforce Interactions SDK | `SalesforceInteractions` |
| Existing customers that have completed their Personalization implementation or have an implementation in progress | Personalization module of the Salesforce Interactions SDK | `Evergage`               |
| Personalization and Data Cloud                                                                                    | Personalization module of the Salesforce Interactions SDK | `SalesforceInteractions` |
| Data Cloud only                                                                                                   | Data Cloud module of the Salesforce Interactions SDK      | `SalesforceInteractions` |

**important:** - If you’re an existing customer who has completed their Personalization implementation or have an implementation in progress, you can continue to use the `Evergage` namespace in your Sitemap and Web and Server-side Campaign Template code.
- We've provided sample code for both SDK namespaces wherever applicable. When copying sample code from articles, ensure that you copy code meant only for the SDK namespace you're using.

## Personalization Module of the Salesforce Interactions SDK

The Personalization module of the Salesforce Interactions SDK facilitates the integration of your website with Personalization. This module provides functions, properties, and methods to track user behavior on your website and send that behavioral data to Personalization, enabling you to build user or visitor behavior profiles. The JavaScript beacon included with the module handles event responses containing personalization web [Campaigns](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-development.md). Users develop these Campaigns through the Personalization UI for display on the website to qualified visitors and use [Campaign Templates](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-development/personalization-template-system.md) to load data, run machine learning, perform A/B testing, and run client-side display logic.

To know more about the web integration process and considerations for development planning, see [Plan a Web Integration](https://developer.salesforce.com/docs/marketing/personalization/guide/web-integration/web-integration-planning.md).

### Key Features

The Personalization module of the Salesforce Interactions SDK provides the following features.

- Identity and cookie management for anonymous and named identity tracking
- Salesforce Interactions SDK JavaScript beacon for website integration
- The Personalization Sitemap for data collection and consent management
- Gears extensions to augment Personalization platform capabilities
- Gears extensions for rendering web campaigns

The following sections introduce each of the preceding features of the Personalization module of the Salesforce Interactions SDK.

## Identity and Cookie Management

The Personalization module of the Salesforce Interactions SDK supports anonymous and named identity tracking using Personalization first-party cookies or by being passed identity information by the website. This system supports the client portion of the Personalization [identity system](https://developer.salesforce.com/docs/marketing/personalization/guide/web-integration/user-identity-mapping.md) by optionally updating client identity with an encrypted nonce for the primary identity to support merging profile identities across different devices and channels. For comprehensive information on how to specify user identities in Personalization, see [User Identity Mapping](https://developer.salesforce.com/docs/marketing/personalization/guide/web-integration/user-identity-mapping.md).

### Personalization First-Party Cookies

The Personalization module of the Salesforce Interactions SDK sets the following two cookies.

- A cookie prefixed with `_evga_` that stores Personalization Identities such as the `anonymousId` or any persisted ID.
- A cookie prefixed with `_sfid_` that stores any consents and their status provided to the Web SDK.

Both cookies end with a string of characters unique to the dataset to which the cookie belongs. These cookies can be cleared for [consent management](#consent-management-through-the-sitemap) purposes when a user doesn’t consent to cookie tracking. The cookies default to having the secure attribute set, but can be overridden at the dataset level under **Settings** > **General Setup** > **Advanced Options** > **Web SDK Cookie Secure Attribute**.

## Web SDK JavaScript Beacon

The JavaScript beacon provided with the Personalization module of the Salesforce Interactions SDK is required for managing the flow of data between the Personalization platform and the SDK libraries used in the client integration. The beacon is a lightweight JavaScript file that enables script-loading functionality on page load, acts as an event message bus, and provides the ability to bootstrap plug-ins for advanced logic and integration. Webpages that don’t contain the JavaScript beacon can’t use Personalization's behavioral tracking or personalization capabilities. For instructions on confirming whether the JavaScript beacon is present on a website page, see [Validate JavaScript Beacon Deployment](https://developer.salesforce.com/docs/marketing/personalization/guide/web-integration/validate-javascript-beacon-deployment.md).

## Sitemap

The Personalization Sitemap system is a configuration-driven integration layer that executes within and is deployed by the Salesforce Interactions SDK. A Sitemap is developed using APIs provided by the Web SDK. A Sitemap integrates key business objects of a website into the Personalization system through event capture. Key business objects are customizable and include, but aren’t limited to, page type information and catalog items, which both support a deep understanding of user affinities within Personalization. Examples of catalog items include products, article content, categories, and other catalog objects. For more information about the Personalization Sitemap and Data Model, see the [Sitemap](https://developer.salesforce.com/docs/marketing/personalization/guide/web-integration/personalization-sitemap.md) and [Data Model](https://developer.salesforce.com/docs/marketing/personalization/guide/data-modeling.md) documentation.

## Consent Management

The Salesforce Interactions SDK includes functions for resolving and storing consent. The Personalization module of the Salesforce Interactions SDK tracks a user if supplied with either no consent value or any value other than an `OptOut` consent with the purpose of `Personalization`. When the Personalization module sees an `OptOut` consent with the purpose of `Personalization`, it doesn’t send events to the user until their consent status changes. The `OptOut` consent with the purpose of `Personalization` is the only consent that causes a behavior change in the Personalization module. While the module can receive and store other consents, they don’t affect collecting or tracking data.

The SDK stores the most recent consent for a purpose in the `_sfid` cookie along with the `lastUpdatedTime` and `lastSentTime` for the consent.

Providing user consent to the SDK can happen either during initialization or by using the `updateConsents` method.

### The Consent Object

`consent` defines a consent object that accepts the following fields.

```typescript
{
  purpose: string, // The purpose for the consent. Example: Personalization
  provider: string, // The consent provider.
  status: string // The consent status. Example: OptIn or OptOut
}
```

The `ConsentWithMetadata` object has the following shape.

```typescript
{
  consent: Consent,
  lastUpdateTime: Date, // The last time the consent was updated
  lastSentTime?: Date // The last time the consent was sent in an event
}
```

### Consent Methods

You can use the following methods to update the `consent` object.

- `getConsents: ConsentWithMetadata[]`

  Returns consent data with the last updated and sent times.

- `updateConsents = (consents: Consent | Consent[]): void`

  Accepts an array of consent objects or a single consent object. This method updates the consent used by the Personalization module of the Web SDK allowing updating consent after initialization.

### Consent Helpers

The Personalization module of the Salesforce Interactions SDK provides the following helpers for setting consent purpose and consent status.

#### ConsentPurpose

```javascript
SalesforceInteractions.mcis.ConsentPurpose = {
  Personalization: "Personalization",
};
```

```javascript
Evergage.ConsentPurpose = {
  Personalization: "Personalization",
};
```

#### ConsentStatus

```javascript
SalesforceInteractions.ConsentStatus = {
  OptIn: "Opt In",
  OptOut: "Opt Out",
};
```

```javascript
Evergage.ConsentStatus = {
  OptIn: "Opt In",
  OptOut: "Opt Out",
};
```

### Consent Management Through the Sitemap

Not all your website's visitors and/or users consent to cookie tracking. To support consent management, the Personalization module of the Salesforce Interactions SDK has been designed to not track activity if a Consent with the Status of `OptOut` and the Purpose of `Personalization` has been provided.

During initialization, the Personalization module of the Salesforce Interactions SDK can accept a `consents` field in the configuration. The `consents` field can accept either an array of Consents or a Promise that resolves an array of Consents. When the `consents` field is provided during initialization, any resolved consents are used by the Personalization module of the Salesforce Interactions SDK.

The following are examples of providing user consent on initialization.

```javascript
SalesforceInteractions.init({
  consents: new Promise((resolve) => {
    SalesforceInteractions.cashDom("#opt-in-personalization").on("click", () => {
      resolve([
        {
          provider: "Consent Provider",
          purpose: SalesforceInteractions.mcis.ConsentPurpose.Personalization,
          status: SalesforceInteractions.ConsentStatus.OptIn,
        },
      ]);
    });
    SalesforceInteractions.cashDom("#opt-out-personalization").on("click", () => {
      resolve([
        {
          provider: "Consent Provider",
          purpose: SalesforceInteractions.mcis.ConsentPurpose.Personalization,
          status: SalesforceInteractions.ConsentStatus.OptOut,
        },
      ]);
    });
  }),
});
```

```javascript
Evergage.init({
  consents: new Promise((resolve) => {
    Evergage.cashDom("#opt-in-personalization").on("click", () => {
      resolve([
        {
          provider: "Consent Provider",
          purpose: Evergage.ConsentPurpose.Personalization,
          status: Evergage.ConsentStatus.OptIn,
        },
      ]);
    });
    Evergage.cashDom("#opt-out-personalization").on("click", () => {
      resolve([
        {
          provider: "Consent Provider",
          purpose: Evergage.ConsentPurpose.Personalization,
          status: Evergage.ConsentStatus.OptOut,
        },
      ]);
    });
  }),
});
```

### Updating Consent Using the updateConsents Method

The Personalization module of the Salesforce Interactions SDK also provides functionality to update consents through the `updateConsents` method. The `updateConsents` method can be called at any time with updated consent for the user.

When the `updateConsents` method is called, if a Consent is sent with the status of `OptOut`, the Personalization module of the Salesforce Interactions SDK sends an event to Personalization with the updated consents. If a Consent with the Purpose of `Personalization` is updated to `OptOut`, the Personalization module of the Salesforce Interactions SDK stops sending events.

The following are examples of calling the `updateConsents` method.

```javascript
const sitemapConfig = {
    global: {
        listeners: [
            SalesforceInteractions.listener("click", "#opt-in-personalization", () => {
                const consent = {
                    provider: "Consent Provider",
                    purpose: SalesforceInteractions.mcis.ConsentPurpose.Personalization,
                    status: SalesforceInteractions.ConsentStatus.OptIn
                };
                SalesforceInteractions.updateConsents(consent);
            }),
            SalesforceInteractions.listener("click", "#opt-out-personalization", () => {
                const consent = {
                    provider: "Consent Provider",
                    purpose: SalesforceInteractions.mcis.ConsentPurpose.Personalization,
                    status: SalesforceInteractions.COnsentStatus.OptOut
                };
                SalesforceInteractions.updateConsents(consent);
            })
        ]
    }
    ...
}
```

```javascript
const sitemapConfig = {
    global: {
        listeners: [
            Evergage.listener("click", "#opt-in-personalization", () => {
                const consent = {
                    provider: "Consent Provider",
                    purpose: Evergage.ConsentPurpose.Personalization,
                    status: Evergage.ConsentStatus.OptIn
                };
                Evergage.updateConsents(consent);
            }),
            Evergage.listener("click", "#opt-out-personalization", () => {
                const consent = {
                    provider: "Consent Provider",
                    purpose: Evergage.ConsentPurpose.Personalization,
                    status: Evergage.ConsentStatus.OptOut
                };
                Evergage.updateConsents(consent);
            })
        ]
    }
    ...
}
```

### Providing Default OptOut Personalization Consent

Since the Personalization module of the Salesforce Interactions SDK doesn’t track users that have provided an `OptOut` Personalization consent, we recommend providing an `OptOut` Personalization consent by default until a user has Opted in. The following are examples of providing an `OptOut` Personalization consent on initialization.

```javascript
SalesforceInteractions.init({
  consents: [
    {
      provider: "Consent Provider",
      purpose: SalesforceInteractions.mcis.ConsentPurpose.Personalization,
      status: SalesforceInteractions.ConsentStatus.OptOut,
    },
  ],
}).then(() => {
  // Logic to get the visitors actual consent
  // Sitemap
});
```

```javascript
Evergage.init({
  consents: [
    {
      provider: "Consent Provider",
      purpose: Evergage.ConsentPurpose.Personalization,
      status: Evergage.ConsentStatus.OptOut,
    },
  ],
}).then(() => {
  // Logic to get the visitors actual consent
  // Sitemap
});
```

When an `OptOut` Personalization consent is provided for a user, no events are tracked. In the preceding example, an `OptOut` Personalization Consent is provided with initialization on every page. If you wish to have the Sitemap execute for a user, you must resolve and set the user's actual consent before initializing the Sitemap.

### Removing Personalization Cookies

The Personalization module of the Salesforce Interactions SDK provides the following helper functions to remove Personalization cookies. You can use this helper function to remove Personalization cookies in scenarios where a user no longer consents to or explicitly requests to cease cookie tracking, or when you wish to remove cookies after a user logs out of your website.

```javascript
document.dispatchEvent(new CustomEvent(SalesforceInteractions.CustomEvents.OnClearCookie), {
  detail: {
    options: {
      domain: domain,
    },
  },
});
```

```javascript
Evergage.removeCookies(domain);
```

By default, if the `domain` isn’t specified, this helper function tries to remove cookies based on the domain configured in the `SalesforceInteractions.init()` function in the `SalesforceInteractions` SDK namespace and the `Evergage.init()` function in the `Evergage` SDK namespace that initializes the JavaScript Beacon. To remove cookies before the beacon is initialized, ensure that you specify the `domain` in the helper function or as part of the detail on the `SalesforceInteractions.CustomEvents.OnClearCookie` CustomEvent.

## Web SDK Gears Extensions

The JavaScript beacon provided with the Salesforce Interactions SDK supports the delivery of custom functionality to augment the client-side functionality of the Personalization platform through Gear extensions. These extensions are JavaScript files delivered and installed through various Gears developed by the Personalization development team.

**important:** Gear development is managed by Personalization. You can file Gear development requests as feature requests on the [Salesforce IdeaExchange](https://trailblazer.salesforce.com/ideaSearch?filter=Marketing+%3E+Interaction+Studio) portal for review by the Personalization Product team members.

## Web Campaign Templates

You can also use Gears extensions in configured [web templates](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-development/personalization-template-system.md) to deliver campaign and personalization content directly to website code so that the website can render it. Personalization includes a built-in Handlebars Gear that supports rendering dynamic content into HTML and CSS styles using the [Handlebars](https://handlebarsjs.com) template language.

## Ad Blockers and Web-based Personalization

Some of your web users have enabled browser extensions that block ads on the websites that they visit. An ad blocker that is set to be highly restrictive can also block personalized experiences. In addition to preventing ads, web users can configure their ad blocker to prevent data collection, including behavioral data. Users who have opted out of data collection have effectively opted out of your personalization efforts.

A highly restrictive ad blocker can block client-side code associated with a web integration, preventing users from receiving recommendations or other personalized experiences. If you want to reach these users with personalization, consider a server-side implementation instead. For a server-side implementation, the Event API can capture most of the same information. One exception is the time a user spends on a page. Depending on your situation, a server-side implementation can be more complex than a web integration solution, so consider the tradeoffs before deciding which approach to use.

**note:** Ad blockers affect client-side implementations for many personalization and analytics vendors, not just web integrations that use the Marketing Cloud Personalization module of the Salesforce Interactions SDK.

<!-- document id=0d4fe02e896f7b41d831c8fdcf95d46fa4c35de871ff87ab9566cf928334653e url=/developer/current/en-us/personalization/personalization/guides/campaign-development/templates/modifying-global-templates.md -->

# Modifying Global Templates

Developers can leverage existing global templates via the Global Templates tab in the Visual Editor to create reusable templates that enable marketers to deliver messages based on behavioral triggers. This guide takes you through modifying the Marketing Cloud Personalization "Global Template: Slide-in With Call-To-Action", and its associated use cases.

## Slide-in With Call-To-Action Global Template

Using the "Slide-in With Call-To-Action" global template, you can deliver attention-grabbing slide-in messages that include a CTA to customers and prospects. You can choose from various trigger options, such as time on page, scroll depth, and inactivity, that determine when the message is supposed to appear.

### Template Configuration

The following steps describe how to configure the Slide-in With CTA global template.

1. In your sitemap, include content zones to target the "Slide-in With Call-To-Action" template. Consider the following when determining your content zone.

   - This template does not replace the selected content zone/selector.
   - This content zone must be present on all pages where the template is supposed to render.
   - Personalization JS can render one campaign per content zone and renders the campaign with the highest priority.

   **note:** As a best practice, create a unique global content zone, such as `global_slide_in`, as shown in the following sample code.

   ```javascript
   const config = {
     global: {
       contentZones: [{ name: "global_slide_in", selector: "body > div.category-menu" }],
     },
   };
   ```

2. Clone the Slide-in With CTA template global template and name it. By default, the cloned template is named `[CLONED] Global template name`.
3. Under **Template Settings**, apply the content zone (or content zones) added during site mapping to the template using the **Content Zones in Template** selector.

   ![Content Zones in Template selector in Template Settings](https://developer.salesforce.com/media/campaign-development/content-zone-selector.png)

4. **_Optional:_** In the **Serverside Code** tab, configure what is shown or made available in the template to the business user. For example, you can add additional scroll depth percentage options that the business user can select from when they're configuring the campaign. The following image illustrates how you can set scroll depth percentages in the **Serverside Code**.

   ![Trigger Options](https://developer.salesforce.com/media/campaign-development/trigger-options.png)

5. **_Optional:_** Configure the look and feel of the slide-in based on business requirements using template handlebars and CSS. The following unique styling options are available for the Slide-In With Call-To-Action template.

   - `animation-duration`: Determines the time in seconds for the slide-in animation to complete
   - `keyframes`: Determines the starting and ending position of the slide-in animation (the direction from which the slide-in slides in).

   The following code depicts example CSS that styles the slide-in element and handlebars that animate it to slide in from the left side of the page.

   ```css
   #evg-slide-in-with-cta {
     position: fixed;
     z-index: 1000000;
     top: auto !important;
     left: 5%;
     bottom: 10vh !important;
     right: auto;
     width: 300px;
     height: 300px;
     border: 1px solid #000;
     color: #fff;
     background-color: #000;
     font-family: inherit;
     animation-name: slideInDesktopMessage;
     animation-duration: 1s;
   }

   @keyframes slideInDesktopMessage {
     from {
       left: -90%;
     }
     to {
       left: 5%;
     }
   }
   ```

   The preceding code slides in the main template element from the left side (-90% to 5%) of the page.

   ![Slide-in animation from the left side of the page](https://developer.salesforce.com/media/campaign-development/slide-in-left.gif)

   The following code depicts example CSS that styles the main template element so that it animates it to slide in from the right side of the page.

   ```css
   #evg-slide-in-with-cta {
     position: fixed;
     z-index: 1000000;
     top: auto !important;
     right: 5%;
     bottom: 10vh !important;
     left: auto;
     width: 300px;
     height: 300px;
     border: 1px solid #000;
     color: #fff;
     background-color: #000;
     font-family: inherit;
     animation-name: slideInDesktopMessage;
     animation-duration: 1s;
   }

   @keyframes slideInDesktopMessage {
     from {
       right: -90%;
     }
     to {
       right: 5%;
     }
   }
   ```

   The preceding code slides in the slide-in element from the right side (-90% to 5%) of the page.

   ![Slide-in animation from the right](https://developer.salesforce.com/media/campaign-development/slide-in-right.gif)

   **note:** To prevent unwanted jumps in the slide-in animation, ensure that the position of the slide-in aligns with the end of the slide-in's animation.

6. To save and publish the template, click **Save** and then click **Publish**.

   **note:** A business user can only reference published templates in a campaign.

<!-- document id=41ba9c31107c2fc7f48087f5a91defe2165cfebf868d70237c3233e12adf3637 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/server-side-campaigns-templates/multiple-server-side-campaign-responses.md -->

# Multiple Server-Side Campaign Responses in a Single Call

It is possible to include multiple campaign responses in a single call. The Event API returns campaign responses for all server-side campaigns that meet the campaign targeting criteria. For example, if you have three personalizations on a single page, you can return multiple campaign responses at once as long as you ensure the following.

- All three campaigns are published
- A user qualifies for all three campaigns

On meeting the preceding criteria, the Event API returns three campaign responses in a single call. The client is responsible for parsing the campaign response data and determining which campaign response to display and where to display it on the page or end system.

As the number of campaigns a client is running increases, it is essential to understand that the number of campaigns returned in a single response can impact latency. Factors that can affect latency include:

- The number of campaigns being returned in a single call
- The amount of data being returned by each campaign
- The complexity of the queries leveraged within each campaign (Einstein Recipes, Einstein Decisions, and so on)

Consider the following best practices when returning multiple campaigns in a single request.

- Limit the campaigns to be returned to what can be visibly rendered to the end user
- Load campaigns that are below the fold in subsequent calls as they come into view

Additionally, to ensure that you are only ever returning the necessary campaigns for a response, we strongly recommend validating that your campaigns use appropriate targeting logic (like page targeting). Without proper targeting logic, you risk unnecessarily returning more campaigns than required and ultimately negatively impacting overall performance.

<!-- document id=3785b84a4322f43f5c5f9158407828da3c6f16cefdf021d19c00e3b56e8536c4 url=/developer/current/en-us/personalization/personalization/guides/custom-interface-template-configuration/properties/multi-select.md -->

# Multiselect Property

## Simple Multiselect

Multiselect input properties are configured similarly to [Select Properties](https://developer.salesforce.com/docs/marketing/personalization/guide/select.md) by using an `@options`, `@lookupOptions`, or `@searchOptions` decorator. The only difference is that the property value for a Multiselect property input is defined as an array.

```typescript
export class SimpleTemplate implements CampaignTemplate {
  @options(["First Option", "Second Option", "Third Option"])
  myOptionProperty: string[];
}
```

![Multiselect](https://developer.salesforce.com/media/interface-template-configuration/MultiSelect.png)

---

## Complex Types As Option Values

You can also configure Multiselect input properties using Complex Types as option values.

```typescript
export class ComplexType {
  firstProperty: string;
  secondProperty: number;
  label: string;
}

export class SimpleTemplate implements CampaignTemplate {
  @options([
    { firstProperty: "one", secondProperty: 1, label: "First Option" },
    { firstProperty: "two", secondProperty: 2, label: "Second Option" },
    { firstProperty: "three", secondProperty: 3, label: "Third Option" },
  ])
  myOptionProperty: ComplexType[];
}
```

![Multi Select](https://developer.salesforce.com/media/interface-template-configuration/MultiSelect.png)

## Dynamic Option Values

An example of a multiselect with dynamic options.

```typescript
export class SegmentReference {
  value: string;
  label: string;
}

export class SegmentLookup implements Lookup<SegmentReference> {
  lookup(context: GearLifecycleContext): SegmentReference[] {
    let segments = context.services.config.findSegments("User");

    return segments.map((segment) => {
      return <SegmentReference>{ value: segment.id, label: segment.name };
    });
  }
}

export class SimpleTemplate implements CampaignTemplate {
  @lookupOptions(() => new SegmentLookup())
  segment: SegmentReference[];
}
```

![Multiselect](https://developer.salesforce.com/media/interface-template-configuration/MultiSelect2.png)

<!-- document id=c08717970cb654ab05f6add4c9d6277287fb8b7b9b45f8e6ef2c63b2fe6e7875 url=/developer/current/en-us/personalization/personalization/guides/web-integration/multisite-implementation-strategy.md -->

# Multisite Implementation Strategy

Marketing Cloud Personalization accounts are similar to Marketing Cloud tenants - customers typically sign up for a single account for their license and can have multiple datasets associated with each account.

Each dataset in Personalization is a separate, siloed data environment. As datasets don’t share data among themselves, the same user could have an independent profile in each dataset. Campaigns, segments, statistics, and integrations are also not shared between datasets. Personalization customers can also set permissions levels for their teams, ensuring that each team has access to the datasets they need in order to use Personalization for their business needs.

It’s common to have a single dataset associated with one web domain. However, it’s possible to have more than one domain on a Personalization license or a domain serving multiple countries in multiple languages. In these cases, dataset design during the discovery process is essential in a successful Personalization implementation.

## Factors Influencing Dataset Design

- How many web domains does the license include? Are they all the same brand, or are they different brands?
- How many countries (or locales) does the domain support?

![Dataset Decision Tree](https://developer.salesforce.com/media/dataset-decision-tree.png)

### Multiple Domains

If there are multiple domains on one Personalization license, either maintain a separate dataset for each domain or combine the domains into a single dataset. Often, it’s best to have a single dataset per domain, but there are good reasons to combine multiple domains into a single dataset. The following sections provide guidance on using a single dataset for multiple domains.

## Designing the Catalog

Depending on the catalog differences between the different sites, there are some things to consider when designing the catalog data model. If the sites do share products with identical IDs, it’s advisable to differentiate between these products by making the IDs unique per site. You could do so by prefixing the IDs that a unique identifier for the site would capture.

For example, consider two sites, `https://foo.example/` and `https://bar.example/`. These two sites share a product with the ID `abc123`. When importing and capturing catalog data, you could prefix this product ID based on the site to differentiate the product in the Personalization Catalog since it could have different attributes depending on the site. On `https://foo.example/`, the ID could become `foo_abc123`, and on `https://bar.example/`, the ID could become `bar_abc123`.

To help differentiate products that exist on different sites in the same dataset, it’s a good idea to track a related catalog object for the site the product appears on. This related catalog object would allow for differentiating products available only on the site the user is on in recipes. Consider the two sites `https://foo.example/` and `https://bar.example/`. When viewing a product on `https://foo.example/` you could set this related catalog object to `foo.example` and when viewing a product on `https://bar.example/` you could set this related catalog object to `bar.example`. Having this related catalog object available would allow adding a recipe exclusion to any recommendations so that only products available on the site the user is on would be recommended.

## Sitemap

When mapping multiple sites to the same dataset, these sites share the Web SDK and Sitemap integration.

### Setting the Cookie Domain

By default, the current domain is set as the `cookieDomain` when initializing the Web SDK. To configure the `cookieDomain` setting, you must dynamically determine which domain to set the cookie on since different sites share the initialization.

The following examples show how to dynamically determine and set a custom `cookieDomain` based on the site where the Web SDK is initializing. The Personalization Web SDK anonymous user IDs are generated separately for each domain. When integrating multiple domains in the same dataset, users tracked anonymously are tracked as separate users across the different domains.

```javascript
const getCookieDomain = () => {
  let currentDomain = window.location.hostname;
  if (currentDomain === "foo.example") {
    return "foo.example";
  } else if (currentDomain === "bar.example") {
    return "bar.example";
  }
};
const currentCookieDomain = getCookieDomain();

SalesforceInteractions.init({
  cookieDomain: currentCookieDomain,
});
```

```javascript
const getCookieDomain = () => {
  let currentDomain = window.location.hostname;
  if (currentDomain === "foo.example") {
    return "foo.example";
  } else if (currentDomain === "bar.example") {
    return "bar.example";
  }
};
const currentCookieDomain = getCookieDomain();

Evergage.init({
  cookieDomain: currentCookieDomain,
});
```

### Initializing the Correct Sitemap

When mapping multiple domains to the same dataset, it’s good practice to have separate Sitemap configurations for each domain if the Page Types and Content Zones defined share names but capture different Interactions. Having Page Types and Content Zones share names makes it possible to share templates and campaigns between the domains. Moreover, if you don't use the same Content Zone names and Page Types, the template editor only shows options for the last domain that the Sitemap was saved for in the Visual Editor.

After you have built the Sitemap configurations for each domain, you must initialize the correct Sitemap configuration based on the domain the user is visiting currently.

The following examples depict a configuration that initializes the correct Sitemap for the domain a user is visiting currently.

```javascript
const getCookieDomain = () => {
  let currentDomain = window.location.hostname;
  if (currentDomain === "foo.example") {
    return "foo.example";
  } else if (currentDomain === "bar.example") {
    return "bar.example";
  }
};
const currentCookieDomain = getCookieDomain();

SalesforceInteractions.init({
  cookieDomain: currentCookieDomain,
}).then(() => {
  let siteAConfig = {
    global: {},
    pageTypeDefault: {
      name: "default",
      interaction: {
        name: "Default Page",
      },
    },
    pageTypes: [
      {
        name: "home",
        isMatch: () => window.location.pathname === "/",
        interaction: {
          name: "Example A Home",
        },
      },
    ],
  };

  let siteBConfig = {
    global: {},
    pageTypeDefault: {
      name: "default",
      interaction: {
        name: "Default Page",
      },
    },
    pageTypes: [
      {
        name: "home",
        isMatch: () => window.location.pathname === "/",
        interaction: {
          name: "Example B Home",
        },
      },
    ],
  };

  if (currentCookieDomain === "foo.example") {
    SalesforceInteractions.initSitemap(siteAConfig);
  } else if (currentCookieDomain === "bar.example") {
    SalesforceInteractions.initSitemap(siteBConfig);
  }
});
```

```javascript
const getCookieDomain = () => {
  let currentDomain = window.location.hostname;
  if (currentDomain === "foo.example") {
    return "foo.example";
  } else if (currentDomain === "bar.example") {
    return "bar.example";
  }
};
const currentCookieDomain = getCookieDomain();

Evergage.init({
  cookieDomain: currentCookieDomain,
}).then(() => {
  let siteAConfig = {
    global: {},
    pageTypeDefault: {
      name: "default",
    },
    pageTypes: [
      {
        name: "home",
        action: "Example A Home",
        isMatch: () => window.location.pathname === "/",
      },
    ],
  };

  let siteBConfig = {
    global: {},
    pageTypeDefault: {
      name: "default",
    },
    pageTypes: [
      {
        name: "home",
        action: "Example B Home",
        isMatch: () => window.location.pathname === "/",
      },
    ],
  };

  if (currentCookieDomain === "foo.example") {
    Evergage.initSitemap(siteAConfig);
  } else if (currentCookieDomain === "bar.example") {
    Evergage.initSitemap(siteBConfig);
  }
});
```

If multiple sites have different Page Types and Content Zones, another method is to use one Sitemap configuration for all domains. With this method, each `pageType` must have logic in its `isMatch` function to determine whether to match for the current page and domain.

The following example depicts using a single Sitemap configuration matching on multiple domains.

```javascript
const getCookieDomain = () => {
    const currentDomain = window.location.hostname;
    if (currentDomain === "foo.example") {
        return "foo.example";
    } else if (currentDomain === "bar.example") {
        return "bar.example";
    }
};
const isFooDomain = () => getCookieDomain() === "foo.example";
const isBarDomain = () => getCookieDomain() === "bar.example";
SalesforceInteractions.init({
    cookieDomain: getCookieDomain()
}).then(() => {
    const sitemap = {
        global: {
            onActionEvent: (actionEvent) => {
                if (isFooDomain()) {
                    //foo.example global onActionEvent
                } else if (isBarDomain()) {
                    //bar.example global onActionEvent
                }
            }
        },
        pageTypes: [
            {
                name: "home_A",
                isMatch: () => {
                    return isFooDomain() && window.location.pathname === "/";
                },
                interaction: {
                    name: "Example A Home"
                }
            },
            {
                name: "home_B",
                isMatch: () => {
                    return isBarDomain() && window.location.pathname === "/";
                },
                interaction: {
                    name: "Example B Home"
               }
            }
        ]
    };
    SalesforceInteractions.initSitemap(sitemap);
});
```

```javascript
const getCookieDomain = () => {
    let currentDomain = window.location.hostname;
    if (currentDomain === "foo.example") {
        return "foo.example";
    } else if (currentDomain === "bar.example") {
        return "bar.example";
    }
}
const currentCookieDomain = getCookieDomain();
const isFooDomain = () => window.location.hostname === "foo.example";
const isBarDomain = () => window.location.hostname === "bar.example";

Evergage.init({
    cookieDomain: currentCookieDomain
}).then(() => {
    const sitemap = {
        global: {
            onActionEvent: (actionEvent) => {
                if (isFooDomain()) {
                    //foo.example global onActionEvent
                } else if (isBarDomain()) {
                    //bar.example global onActionEvent
                }
            }
        },
        pageTypes: [
            {
                name: "home_A",
                isMatch: () => {
                    return return isFooDomain() && window.location.pathname === "/";
                },
                action: "Example A Home"
            },
            {
                name: "home_B",
                isMatch: () => {
                    return isBarDomain() && window.location.pathname === "/";
                },
                action: "Example B Home"
            }
        ]
    };
    Evergage.initSitemap(sitemap);
})
```

### Page Types and Content Zones

To use different Sitemap configurations for multiple domains, keep the same `pageType` names for equivalent pages on different domains. You can differentiate which site the user is visiting using Interactions and Catalog Objects. For example, a product detail page on `https://foo.example` and a product detail page on `https://bar.example` must share the same `product_detail` Page Type.

For Content Zones, use consistent names across domains to make it easier to share templates and campaigns. You can, however, have different Content Zone selectors across domains.

**important:** If you don't use the same Content Zone names and Page Types, the template editor only shows options for the last domain that the Sitemap was saved for in the Visual Editor.

<!-- document id=4684b20503fc8855fc6b1e787ab052fd0437fba64604013694033e56457f9b74 url=/developer/current/en-us/personalization/personalization/guides/custom-interface-template-configuration/properties/number.md -->

# Number Property

## Simple Number Input

A basic numeric input.

```typescript
simpleNumberProperty: number = 0;
```

![Simple Number Property](https://developer.salesforce.com/media/interface-template-configuration/SimpleNumber.png)

---

## Units Decorator

Units can be displayed next to a numeric input using the `@units` decorator.

```typescript
@units("days")
campaignDelay : number = 7;
```

![Units](https://developer.salesforce.com/media/interface-template-configuration/Units.png)

---

## Enumerated Values

A static list of options can be provided using the TypeScript _String Literal_ type system. Doing so provides a dropdown menu with the options.

```typescript
simpleOption: 0 | 5 | 10;
```

For more complex dropdown examples, see [Select Property](https://developer.salesforce.com/docs/marketing/personalization/guide/select.md).

---

## See Also

- [Select Property](https://developer.salesforce.com/docs/marketing/personalization/guide/select.md)
- [Arrays](https://developer.salesforce.com/docs/marketing/personalization/arrays.md)

<!-- document id=658ec8f2c5ee00f45acf3b09f2fb1e642902fea9c42e90030e7b4b9f28d30bc0 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/open-time-email-campaigns-templates.md -->

# Open Time Email Campaigns and Templates

Marketing Cloud Personalization's Open Time Email (OTE) Campaigns and Item Templates enable you to deliver content and product recommendations personalized at the time a recipient opens an email. You can develop OTE campaigns and item templates with the Personalization UI and generate HTML code to insert into an email campaign that you can send using your existing email marketing system. You only need basic HTML knowledge to build OTE campaigns and templates within the UI. However, you may require developer assistance to customize and extend the generated HTML.

**important:** Open Time Email campaigns currently don't support localization.

This section contains links to articles and code samples that help you customize and work with the HTML code generated via Personalization OTE campaigns and templates.

- [Render non-western characters in an OTE Template](https://developer.salesforce.com/docs/marketing/personalization/guide/open-time-email-campaigns-templates/render-non-western-characters.md)
- [Capture an OTE Campaign URL](https://developer.salesforce.com/docs/marketing/personalization/guide/open-time-email-campaigns-templates/capture-email-campaign-url.md)
- [Add Third Party Tracking Parameters to Open Time Email Campaigns](https://developer.salesforce.com/docs/marketing/personalization/guide/open-time-email-campaigns-templates/third-party-tracking-for-email-campaigns.md)
- [Image Generation in Open Time Email Campaigns](https://developer.salesforce.com/docs/marketing/personalization/guide/open-time-email-campaigns-templates/image-generation-email-campaigns.md)

<!-- document id=1439f355d2fb9ec1abca3415bd4eeb627bb7bdd09ad3302f50c84d33a91a978a url=/developer/current/en-us/personalization/personalization/guides/web-integration/page-types.md -->

# Page Types

Page Types are used to establish what pages on a website and what data on these pages you'd like Marketing Cloud Personalization to track. Page Types also define the Content Zones, Events, Templates, and Catalog data to be tracked by Personalization on a page. An Personalization Sitemap comprises multiple `pageType` configurations. You can apply a single `pageType` configuration to multiple pages on your website.

## Page Config Fields

The following table summarizes the fields that a `PageConfig` accepts.

| Field Name      | Expected Value Type                       | Required | Description                                                                                                           | Namespace                |
| --------------- | ----------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `name`          | String                                    | **Yes**  | The name of the page type. Example: Homepage, Product Detail                                                          | Both                     |
| `isMatch`       | `() => boolean \| () => Promise<boolean>` | **Yes**  | The function that determines if the current page matches the config                                                   | Both                     |
| `action`        | String                                    | No       | The action that is sent when the config is evaluated                                                                  | `Evergage`               |
| `itemAction`    | String                                    | No       | The property of ActionEvent used to identify user actions taken on catalog items such as "Purchase" or "AddToCart".   | `Evergage`               |
| `interaction`   | `Interaction`                             | No       | The property of `ActionEvent` used to identify user actions taken on catalog items such as "Purchase" or "AddToCart". | `SalesforceInteractions` |
| `catalog`       | `CatalogConfig`                           | No       | The catalog data to be captured                                                                                       | `Evergage`               |
| `cart`          | `CartConfig`                              | No       | The cart data to be captured                                                                                          | `Evergage`               |
| `order`         | `OrderConfig`                             | No       | The order data to be captured                                                                                         | `Evergage`               |
| `contentZones`  | `ContentZone[]`                           | No       | The content zones defined on the page                                                                                 | Both                     |
| `listeners`     | `Listener[]`                              | No       | The event listeners to be bound when this configuration is evaluated                                                  | Both                     |
| `onActionEvent` | `(event: ActionEvent) => ActionEvent`     | No       | The function to modify the outgoing `ActionEvent`                                                                     | Both                     |

## Common Page Types

Depending on your business vertical, the objective of your website, and the type of content it serves, certain page types are recommended to be mapped over others.

### General Page Types

The following table outlines general page types that you can define on any website.

| Page Type        | Description                      |
| ---------------- | -------------------------------- |
| `home`           | The website's homepage           |
| `blog`           | The blog's homepage              |
| `blog_detail`    | A blog post                      |
| `search`         | The search page                  |
| `search_results` | The search results page          |
| `register`       | The register page                |
| `sign_in`        | The sign-in page                 |
| `account`        | The account overview page        |
| `error_page`     | An error page. Example: 404 Page |

### Commerce Page Types

The following table outlines page types that are recommended for a commerce website.

| Page Type            | Description                                                   |
| -------------------- | ------------------------------------------------------------- |
| `product_detail`     | A product detail page                                         |
| `brand`              | A brand detail page                                           |
| `department`         | A department overview page                                    |
| `category`           | A category page, sometimes referred to as a product list page |
| `cart`               | The shopping cart                                             |
| `checkout`           | The checkout pages                                            |
| `order_confirmation` | The order confirmation page                                   |

### B2B Page Types

The following table outlines page types that are recommended for a B2B website.

| Page Type  | Description                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------- |
| `product`  | A specific product offering                                                                 |
| `solution` | A group of offerings, high-level capability, or industry                                    |
| `article`  | A details page for articles. For example, White Papers, Technical Specs                     |
| `event`    | A details page for events. For example, Webinars, Conferences                               |
| `learning` | A details page for learning content. For example, Classes, Playbooks, Forums, Documentation |

### Default Page Type

The following table outlines the naming convention to follow for the `pageTypeDefault` configuration in the sitemap.

| Page Type | Description                           |
| --------- | ------------------------------------- |
| `default` | Any page that isn't explicitly mapped |

<!-- document id=7c93d52adb260b893679ded42839af7f08d4a0853f2666caec2b06808746fb7b url=/developer/current/en-us/personalization/personalization/guides/web-integration/site-impact-approach.md -->

# Personalization Site Impact Approach

The Personalization module of the Salesforce Interactions SDK runs on web pages to gather relevant information, and modify content to provide a personalized experience to the web page’s visitors. This document covers details on the expected behavior of the SDK regarding page load performance.

It is important to note that the client-side JavaScript served by Marketing Cloud Personalization is categorized into three main sections within the same file, in the following order:

- The Personalization module of the Salesforce Interactions SDK
- Beacon Extensions
- Sitemap

While the SDK portion alone remains the same for every integration, Beacon Extensions and Sitemap can be different and could have special considerations regarding site impact.

## Integration

Downloading and executing Interaction Studio’s JavaScript inherently impacts a site’s performance just by being a new piece of content to load.

Personalization minimizes the impact by doing the following.

- Serving via a global Content Delivery Network (CDN) with over 40 points of presence around the globe.
- Utilizing our CDN option to serve stale; even if the SDKs origin server is unavailable or slow, we continue to serve a cached version of the SDK.
- Client-side caching, to ensure only the first page load requires downloading of the file.
- Keeping the Web SDK small, under 50 KBs compressed with gzip, before optional Beacon Extensions and the Sitemap.

While the preceding points apply to all Web SDK integrations, there are two methods for integrating Personalization into a website - Synchronous and Asynchronous. Each method has different levels of impact on the site.

### Synchronous Integration

With a synchronous integration, the Interaction Studio’s JavaScript downloads when it is present on the page before the browser executes the rest of the page. In doing so, the [Flicker Defender](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/web-campaigns-templates/flicker-defender.md) Beacon Extension prevents content that could be personalized from appearing before it can be personalized, and tracking can take place as soon as possible.

### Asynchronous Integration

With an asynchronous integration, Interaction Studio’s JavaScript downloads alongside the rest of the page’s content loading. Flicker Defender does not function in asynchronous integrations.

## Integration Failures

Personalization uses multiple industry-standard CDN providers. In the unlikely scenario that one of them has an outage, we can quickly reconfigure Personalization to use another provider.

**note:** You can view Personalization CDN statuses by visiting [Salesforce Trust](https://trust.salesforce.com/).

If Interaction Studio’s CDN is unavailable, the request to load the SDK would fail, or timeout, therefore resulting in no personalization occurring. For synchronous integrations, the page's loading is delayed until failure.

## Execution

After the JavaScript is downloaded, it executes in the order of content (Web SDK, Beacon Extensions, Sitemap). The targeted time for executing the Web SDK’s JavaScript and calls to initialize the Web SDK via the Sitemap is in under 30 milliseconds.

### Execution Failures

Script failures inside the Web SDK, Beacon Extensions, and Sitemap are caught and logged to prevent the scripts from negatively impacting the site’s core functionality. You can track errors within Interaction Studio’s event stream to help identify resolutions in cases where the Sitemap errors prevent personalization.

## Event Requests

After execution, the JavaScript beacon sends an event to Interaction Studio’s Event API, and its response will contain any personalization campaigns for which the user has qualified. Personalization targets 20 ms for all server-side execution. End-user response time is subject to the performance of the internet connection.

### Request Failures

These requests have no impact on the page loading and do not cause failures for your end user. If [Flicker Defender](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/web-campaigns-templates/flicker-defender.md) is active, hidden content will redisplay after the configured timeout, with a default of 2.5 seconds from the time the beacon extension first ran.

## See Also

- [Salesforce Trust](https://trust.salesforce.com/)

<!-- document id=9ef057a89758dfb9f686cb988a5ee0915cdb71f048ab2e1e12dd5a57cdf0ea3d url=/developer/current/en-us/personalization/personalization/guides/campaign-development/personalization-template-system.md -->

# Personalization Template System

Marketing Cloud Personalization's template system, composed of Web Templates & Server-Side templates, provides developers with the ability to customize and configure templates to support their business user's use case needs. A template developer has complete control over each component of the template and can determine which aspects of the campaign experience a business user can manipulate. After a developer publishes a template for a business user to use in a campaign, it becomes a reusable tool in the business user's optimization arsenal that allows a business to test and learn at speed.

While developers can configure custom templates from scratch, Personalization accounts are equipped with various global templates specifically designed to cover some of the most common and powerful use cases. These templates require minimal edits to leverage out of the box or can act as the starting point for new template creation. The global templates are great use case accelerators and living/breathing examples of template code in action.

For more information on global templates, see [Web Campaign Template Properties](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_template_properties.htm) on Salesforce Help.

## Template Implementation Options

Personalization has two types of templates available for developers to configure.

- **Web Templates:** Web templates consist of four essential parts: Server-Side Code, Client-Side Code, Handlebars, and CSS. They are used when the Personalization module of the Salesforce Interactions SDK is responsible for rendering the campaign experience on the client's site. Web templates also leverage the web content zones mapped during the website implementation. They determine where a campaign can render on the website.
- **Server-Side Templates:** Server-side templates only use server-side code and are used to pass a JSON payload with customer or campaign response data for another system to consume and render.

## Template Context

Data that we refer to as the `context` drives the content displayed in templates. The data in the `context` is derived server-side by Personalization from the configuration of the campaign that is using the template. After it is derived on the server, the `context` is passed to the client browser, where the client-side JavaScript can choose what to do with it, including joining the `context` with the HTML and rendering it.

## Template Components

The following documents include information and instructions on approaching each component of a template.

- [Template Handlebars](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/web-template-handlebars.md)
- [Template CSS](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/web-template-css.md)
- [Template Client JavaScript](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/template-client-javascript.md)
- [Template Server TypeScript](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/template-server-typescript.md)

## Global Web Templates

Personalization provides several [pre-built global templates](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_template_properties.htm) for common personalization use cases. Examples of pre-built global templates include hero banners, popups, product recommendations, info bars, and so on. These templates are highly customizable to suit individual needs and can save developers a significant amount of time over creating a template from scratch. New global templates are being developed and released regularly to meet a variety of web channel campaign use cases.

To use a global web template, do the following.

1. Choose the global template that most closely matches your business use case.
2. Clone the template.
3. Modify the template code to meet business requirements.

For developer guidance in completing the preceding tasks and best practices for working with global web templates, refer to the [Get Started with Global Web Templates](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/get-started-global-web-templates.md) documentation.

## See Also

- [_Salesforce Help_: Web Campaign Template Properties](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_template_properties.htm)

<!-- document id=2a2018c38c3362bbd4a5da849ae7989cbd6f9ffd3fb96a3b6186174e527cbc6b url=/developer/current/en-us/personalization/personalization/guides/web-integration/web-integration-planning.md -->

# Plan a Web Integration

Combined with helpful tips and tricks, the steps in this document reflect how our internal development teams approach implementations. Follow these steps in the correct order as guidance for planning your Marketing Cloud Personalization web integration.

## Step 1: Implementation Planning

### Discovery

During the Personalization discovery process, a solution architect works with the Personalization customer to understand the business context for the Personalization web implementation, any web campaign requirements, and the web-channel solution architecture to implement. Ideally, the implementor comes away from the discovery process with a deep understanding of the website's structure and what data is available for collection by Personalization.

The following list details all the tasks the implementation team carries out during this process.

- Establish the business context and goals of any web campaigns, along with requirements for the associated web templates. For specific technical documentation about Campaigns and Templates, see the [Web Templates](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/personalization-template-system.md) documentation on this site and [About Web Campaigns and Templates](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign.htm) on Salesforce Help.
- Identify the identity attributes necessary for your implementation. Take careful consideration when deciding what identities to use; since identity setup is permanent, it has significant implications for your deployment. Refer to the following documentation for detailed information about how the identity system functions and how you can configure it for use with the web SDK.
  - [Identity Management](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity.htm)
  - [Identity Types and Attributes](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity_type_attributes.htm)
  - [Configure the Identity System for the Web SDK](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity_web_sdk_configure.htm)

Additional considerations:

- If the client is implementing multiple sites on one account, our [Multisite Implementation Strategy](https://developer.salesforce.com/docs/marketing/personalization/guide/multisite-implementation-strategy.md) documentation is helpful.
- If the site is a Single Page Application (SPA), please refer to the [Single Page App Handling](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.md#single-page-app-handling) documentation.

### Blueprint

The [site-mapping blueprint](https://developer.salesforce.com/docs/marketing/personalization/guide/personalization-sitemap.md#sitemap-blueprint) is all about planning. A sitemap blueprint is a skeleton for the structure of your sitemap. It serves as a guide for the developer writing the sitemap code and a reference for developers unfamiliar with a particular implementation. In the sitemap blueprint, you define the page types to be mapped, how the platform treats them, what relevant data is available on each page chosen for mapping, and where individual values to be collected are found within the site.

Creating a good sitemap blueprint is the part of the implementation process that is key to developing the data model. Ensure that the decisions made during blueprinting make sense from a technical standpoint. For more information about data modeling, see the [Data Modeling](https://developer.salesforce.com/docs/marketing/personalization/data-modeling.md) documentation.

It's also essential to keep the client's use cases in mind while developing your blueprint to ensure you create a data model capable of supporting those cases. Additionally, create the blueprint document collaboratively; it's crucial to involve both a business user and a technical resource familiar with the product throughout this process.

After the blueprint has the overall sitemap structure in detail, we recommend adding to the blueprint where each piece of data to be collected can be found on the client's website.

Ensure that you call out all identities needed for this implementation in your blueprint. Finally, get your technical resource to validate whether the values for identity attributes are available on the site and/or through ETL and that all of the identity types you are planning to configure will aid your use cases.

## Step 2: Sitemap Development

You can start the Personalization web integration by deploying the [JavaScript web beacon](https://developer.salesforce.com/docs/marketing/personalization/web-integration.md#web-sdk-javascript-beacon) on all pages that you'd like Personalization to monitor. Typically, the team or individual responsible for deploying software to the company website carries out this task.

[Validate the JavaScript Beacon deployment](https://developer.salesforce.com/docs/marketing/personalization/guide/validate-javascript-beacon-deployment.md), either before or during the sitemap development process. Next, develop the sitemap configuration for all page types and test the sitemap data ingestion to ensure that it meets the anticipated web campaign requirements. For more information on the sitemap development process, see [Sitemap Development](https://developer.salesforce.com/docs/marketing/personalization/guide/personalization-sitemap.md).

### Use a Test Dataset During Development

Leveraging a test dataset to hone your sitemap allows you to experiment during the early stages of the implementation process. It helps ensure that any data captured while working on a sitemap does not contaminate the data in your production environment. Any data captured in your production dataset is factored into the catalog structure, campaign targeting logic, and machine learning recipe training. Hence, it is essential to avoid polluting your production dataset with unwanted data elements. Most importantly, editing and revising sitemap code directly in production can lead to incomplete and unvalidated code running live on the client's site.

Creating and using a test dataset is a simple but critical measure to ensure safe sitemap iteration and a pristine production environment. You can create a test dataset by referring to the instructions listed in the [Personalization Datasets](https://help.salesforce.com/s/articleView?id=sf.mc_pers_datasets.htm) article on Salesforce Help.

### Use the Salesforce Interactions SDK Launcher to Work on Your Test Dataset with the Sitemap Editor

First, [Validate the JavaScript Beacon Deployment](https://developer.salesforce.com/docs/marketing/personalization/guide/validate-javascript-beacon-deployment.md) to check whether the site already has the JavaScript beacon installed. Then, install the Salesforce Interactions SDK Launcher by referring to the [Install the Salesforce Interactions SDK Launcher](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_interactions_sdk_launcher.htm) documentation. When using your test dataset and viewing the site in your browser, the option you enable on the Salesforce Interactions SDK Launcher changes based on the presence of the JavaScript beacon. If the beacon is live on the site, enable **Force Web SDK URL**. If the beacon is not live on the site, enable **Inject Web SDK**. For more information on each of these scenarios, see [Set Up the Visual Editor](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_visual_editor.htm) on Salesforce Help.

Throughout the development process, remember to validate the events sent by your sitemap using all of the methods outlined in the [Sitemap Event Validation](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-event-validation.md) documentation. Doing so enables you to identify any timing issues, errors, or unexpected behavior caused by your sitemap code as they occur.

If you are capturing any data from a form as part of your sitemap, remember that it is best to collect form entry data upon form submission _only_. Following this practice makes sure that you only collect data that was truly intended to be submitted by the user. Consequently, this practice also helps enhance the reliability and accuracy of the data since it would have undergone and passed the same validation processes used to collect these values natively on the client site.

Finally, ensure that all identities are configured appropriately according to the blueprint. To know more about configuring identity types and attributes, see [Identity Types and Attributes](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity_type_attributes.htm).

For more information on Sitemap development, see:

- [Sitemap Development in Personalization](https://developer.salesforce.com/docs/marketing/personalization/guide/personalization-sitemap.md)
- Example Sitemaps
  - [Example Financial Services Sitemap](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps/financial-services.md)
  - [Example ecommerce Sitemap](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps/ecommerce.md)
  - [Example B2B Sitemap](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps/b2b.md)

## Step 3: Sitemap Validation

When your sitemap code appears to be in good shape, review your progress alongside the [Best Practices for Data Capture Using Site Mapping](https://developer.salesforce.com/docs/marketing/personalization/guide/data-capture-best-practices.md). After reviewing these practices and checking that your code works as intended, pass off your sitemap code for the next phase of code review within your organization and edit them based on the feedback you get.

## Step 4: Moving an Approved Sitemap to Production

**important:** If the client's site already has the beacon corresponding to the production dataset integrated into their site, adding a sitemap code to that dataset immediately makes the implementation live and data collection begin. Ensure that the client is ready for this step before proceeding.

This process involves ensuring that the production dataset is configured in the same way as the test dataset you have been using to ensure everything works as expected.

- Reproduce catalog setup from the test dataset in the production dataset.
  - The catalog in the production dataset can be maintained throughout the development process to reflect the Catalog as it gets finalized in your test dataset.
- Paste the completed sitemap code into the production dataset. Make sure you are saving your sitemap code through the web **Sitemap Editor** accessed via the **Visual Editor**.
- Reproduce all recipes and segments created in the test dataset to support your use-cases and/or reporting efforts.
- Configure any third-party integrations from the test dataset in production.
- Configure any feeds from the test dataset in production.
- If development of campaigns and templates began in a test dataset, the following steps are often required.
  - Export templates from the test dataset and import them into production.
  - Reproduce all campaigns created in the test dataset.

## Step 5: Create Templates and Campaigns

**important:** As a best practice, complete the sitemap and move it to production before creating any templates or campaigns. Ideally, all of your campaigns and templates are created only one time directly in the production dataset.

Configure and test the web templates required to support the anticipated web campaigns. For guidance, refer to articles in the [Campaign Development](https://developer.salesforce.com/docs/marketing/personalization/campaign-development.md) section of this site and the [About Web Campaigns and Templates](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign.htm&type=5) article on Salesforce Help.

After you have developed your campaigns, debug them using the [Web Campaign Debugger](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/web-campaigns-templates/campaign-debugger.md). Also, watch the [Event API Responses](https://developer.salesforce.com/docs/marketing/personalization/event-api/event-api-responses.md) directly in the **Network** tab of your browser’s developer tools.

If work on campaigns and templates in the production dataset needs to begin before the sitemap is complete, you _can_ create campaigns and templates within your test dataset. However, be mindful of the following.

- Cloning a dataset does not carry over data, campaigns, or templates.
- If templates are built on a test dataset, you have to individually export and then import each template from the test dataset into the production dataset before you go live with them.
- Campaigns built on the test dataset have to be reproduced manually on the production dataset.

Both templates and campaigns rely on the sitemap in some way to function properly. Without a completed sitemap, it can be difficult to develop a template that works long term, considering that the sitemap is still in flux. Recipes and segmentation depend on the proper implementation of the sitemap based on the discovery and blueprinting processes.

## See Also

- [_Salesforce Help_: About Web Campaigns and Templates](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign.htm)
- [_Salesforce Help_: Identity Management](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity.htm)
- [_Salesforce Help_: Install the Salesforce Interactions SDK Launcher](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_interactions_sdk_launcher.htm)
- [_Salesforce Help_: Set Up the Visual Editor](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_visual_editor.htm)
- [_Salesforce Help_: Personalization Datasets](https://help.salesforce.com/s/articleView?id=sf.mc_pers_datasets.htm)

<!-- document id=744cb484d9c707b4ee5db2954881432e5c33b30a766de31ca539e1fa322c004b url=/developer/current/en-us/personalization/personalization/guides/additional-apis/principals-api.md -->

# Principals API

Principals are users with access to the Marketing Cloud Personalization platform. The Personalization Principals API enables you to retrieve a full list of your Principals, which can help you adhere to various governance, risk, and compliance (GRC) guidelines.

## Method and Endpoint

`GET` `/api/principals`

## Request URL

`https://<accountName>.<instance>.evergage.com/api/principals`

### URL Parameters

| URL Parameter | Required? | Description                                                                                                                                                                                                                                            |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `accountName` | Yes       | The Personalization account name. You can find the `accountName` by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the account name is `demo`.        |
| `instance`    | Yes       | The Personalization instance identifier. You can find this value by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the instance identifier is `us-1`. |

## Response Content Type

- `application/json`

## Authorization

`Authorization: Basic <base64-encoded-API-token>`

The Principals API uses API tokens to authenticate requests. Your API token must be a strict Base64 encoding of your API Key ID and its API Secret Key, separated by a colon. You can use an existing API token if it has the required permissions. Alternatively, you can ask an account administrator to generate a new one from the Personalization UI. For more information on API tokens, see [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm) on Salesforce Help.

Alternatively, if you use [cURL](https://curl.se/docs/manpage.html) to interact with the API, you can send your API Key ID and its API Key Secret using the `-u "apiKeyId:apiKeySecret"` command-line option. cURL automatically converts the `apiKeyId:apiKeySecret` pair into a Base64-encoded string and adds `Authorization: Basic <base64-encoded-API-token>` to the request header.

## Request Example

The following is an example API request sent using cURL.

```bash
curl -X GET \
     -H 'Content-Type: application/json' \
     -u "apiKeyId:apiKeySecret" \
     "https://<accountName>.<instance>.evergage.com/api/principals"
```

## Response Example

The following is an example of a response to a valid `GET` request made to the Principals API endpoint.

```json
[
  {
    "created": 1631213493797,
    "createdBy": null,
    "updated": 1631213493797,
    "updatedBy": null,
    "principalId": "username1324952157-apptegic.com",
    "accountId": "localtest",
    "type": "USER",
    "description": "Description-1324952157",
    "firstName": "FirstName-1324952157",
    "lastName": "LastName-1324952157",
    "email": "1324952157@example.com",
    "avatarImageUrl": null,
    "twoFactorAuthEnabled": false,
    "dswbAccessEnabled": false,
    "supportTeamMember": false,
    "sftpDataset": null,
    "enabled": true,
    "groups": [],
    "grantedAuthorities": [],
    "roles": [],
    "ipWhitelist": [],
    "requirePasswordChangeOnNextLogin": false,
    "lastLoginDate": 1631213493898,
    "lastLoginIP": "0.0.0.1",
    "id": "username1324952157-apptegic.com",
    "principalAndTenantId": "username1324952157-apptegic.com:localtest"
  },
  {
    "created": 1631213493798,
    "createdBy": null,
    "updated": 1631213493798,
    "updatedBy": null,
    "principalId": "username1324952158-apptegic.com",
    "accountId": "localtest",
    "type": "USER",
    "description": "Description-1324952158",
    "firstName": "FirstName-1324952158",
    "lastName": "LastName-1324952158",
    "email": "1324952158@example.com",
    "avatarImageUrl": null,
    "twoFactorAuthEnabled": false,
    "dswbAccessEnabled": false,
    "supportTeamMember": false,
    "sftpDataset": null,
    "enabled": true,
    "groups": [],
    "grantedAuthorities": [],
    "roles": [],
    "ipWhitelist": [],
    "requirePasswordChangeOnNextLogin": false,
    "lastLoginDate": 1631213493899,
    "lastLoginIP": "0.0.0.1",
    "id": "username1324952158-apptegic.com",
    "principalAndTenantId": "username1324952158-apptegic.com:localtest"
  }
]
```

## See Also

- _Salesforce Help_: [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm)

<!-- document id=45a7ddb37ba32d5e3f0d9123bf3e24a14990771479385fdf0056a7b7f5d0b922 url=/developer/current/en-us/personalization/personalization/guides/custom-interface-template-configuration/properties.md -->

# Properties

- [Boolean Property](https://developer.salesforce.com/docs/marketing/personalization/guide/properties/boolean.md)
- [String Property](https://developer.salesforce.com/docs/marketing/personalization/guide/properties/string.md)
- [Number Property](https://developer.salesforce.com/docs/marketing/personalization/guide/properties/number.md)
- [Color Property](https://developer.salesforce.com/docs/marketing/personalization/guide/properties/color.md)
- [DateTime Property](https://developer.salesforce.com/docs/marketing/personalization/guide/properties/datetime.md)
- [Complex Property](https://developer.salesforce.com/docs/marketing/personalization/guide/properties/complex-object.md)
- [Select Property](https://developer.salesforce.com/docs/marketing/personalization/guide/properties/select.md)
- [Multiselect Property](https://developer.salesforce.com/docs/marketing/personalization/guide/properties/multi-select.md)

<!-- document id=5057ad344edbe4a2f0cc47bf263797979963765b64b9b017df341b0eab77f0f8 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/campaign-template-apis/recommendations.md -->

# Recommendations

Marketing Cloud Personalization Recommendations uses a default gear to fetch recommendations based on the current user and selected recipe. Ultimately, the Recommendations service supplies all recommendations provided to the applicable gear component contexts in gears.

The Recommendations gear enables you to configure a campaign template to control what a business user can configure to drive recommendations for the template.

## Usage

To use and configure the Recommendations gear in a campaign template, do the following.

1. Add `import { RecommendationsConfig, recommend } from "recs";` to your template's server-side TypeScript. Optionally, to only return item IDs instead of full items, import `recommendIdsOnly` instead of `recommend`.
2. Add a `RecommendationsConfig` property to your template, and determine what to restrict from the business user, if anything.

   - No restrictions:

     ```typescript
     recsConfig: RecommendationsConfig = new RecommendationsConfig();
     ```

   - Restrict business users to be able to recommend only a specific type of catalog items:

     ```typescript
     recsConfig: RecommendationsConfig = new RecommendationsConfig().restrictItemType("Product");
     ```

   - Restrict business users to a specific maximum number of recommendations:

     ```typescript
     recsConfig: RecommendationsConfig = new RecommendationsConfig().restrictMaxResults(4);
     ```

   - Restrict business users to both a specific type of catalog item and a specific maximum number of recommendations:

     ```typescript
     recsConfig: RecommendationsConfig = new RecommendationsConfig()
       .restrictItemType("Product")
       .restrictMaxResults(4);
     ```

   - Restrict business users to a specific type of catalog item and programmatically override an on-page anchor that is used by the recipe:

     ```typescript
     recsConfig: RecommendationsConfig = new RecommendationsConfig()
       .restrictItemType("Product")
       .overrideOnPageAnchor(itemId, itemType);
     ```

3. Use the `recommend` function to use the configuration property of type `RecommendationsConfig` you added.

## Example Templates

The following example depicts the usage of the Recommendations gear in a campaign template.

```typescript
import { RecommendationsConfig, recommend } from "recs";

export class ExampleRecommendationsTemplate implements CampaignTemplateComponent {
  recsConfig: RecommendationsConfig = new RecommendationsConfig().restrictItemType("Product");

  run(context: CampaignComponentContext) {
    return {
      products: recommend(context, this.recsConfig),
    };
  }
}
```

You can also use the `recommendIdsOnly` function to return only the Item IDs in order of relevance, as shown in the following example.

```typescript
import { RecommendationsConfig, recommendIdsOnly } from "recs";

export class ExampleRecommendationsTemplate implements CampaignTemplateComponent {
  recsConfig: RecommendationsConfig = new RecommendationsConfig().restrictItemType("Product");

  run(context: CampaignComponentContext) {
    return {
      products: recommendIdsOnly(context, this.recsConfig),
    };
  }
}
```

The following example shows the `overrideOnPageAnchor` method using a Product from a Triggered Campaign context as an on-page anchor for the recipe.

```typescript
export class ExampleRecommendationsTemplate implements CampaignTemplateComponent {
  recsConfig: RecommendationsConfig = new RecommendationsConfig().restrictItemType("Product");

  run(context: CampaignComponentContext) {
    if (context?.trigger) {
      const triggerContext = context.trigger as CatalogTrigger;

      if (triggerContext?.itemIdsByType?.["Product"]?.length) {
        const productId = triggerContext.itemIdsByType["Product"][0];
        this.recsConfig.overrideOnPageAnchor(productId, "Product");
      }
    }

    return {
      products: recommend(context, this.recsConfig),
    };
  }
}
```

## Locales

If a dataset has locales configured, the Recommendations gear returns items specific to the user's locale. If a user doesn’t have a locale preference, it returns items specific to the dataset's default locale. Any item returned from the Recommendations API is translated into the user's language, provided a locale item specific to that language exists.

<!-- document id=f22a506941201797042d4a5eab65c5329983fb8352375bd3f2932759a352be2b url=/developer/current/en-us/personalization/personalization/guides/campaign-development/open-time-email-campaigns-templates/render-non-western-characters.md -->

# Render Non-Western Characters in OTE Templates

Along with personalizing content and product recommendations sent via email campaigns at open time, Marketing CLoud Personalization Open Time Email (OTE) item templates enable you to build localized email campaigns for recipients in some non-Western locales. The Noto Sans CJK fonts are built in to the OTE image generator, so the following fonts can be used in OTE templates to display text in Simplified Chinese, Traditional Chinese, Japanese, or Korean.

- Noto Sans CJK SC
- Noto Sans CJK TC
- Noto Sans CJK JP
- Noto Sans CJK KR

**note:** Previously, we recommended loading the Noto Sans CJK SC/TC/JP/KR fonts from [Google Fonts](https://fonts.google.com/) as web fonts. Now that the Noto Sans CJK fonts are built in to the OTE image generator, using web fonts is no longer necessary and is highly discouraged. Non-Western languages other than Simplified Chinese, Traditional Chinese, Japanese, or Korean, are currently not supported. If you need support for another non-Western language, please submit a feature request to [Salesforce IdeaExchange](https://trailblazer.salesforce.com/ideaSearch?filter=Marketing+%3E+Interaction+Studio).

The following code sample shows how to use the [Noto Sans CJK JP](https://fonts.google.com/specimen/Noto+Sans+JP) font in an OTE item template to render the product label `彼らの機器や装置はすべて生命体だ。` in Japanese:

```html
<!--CSS declarations-->
<style>
  body {
    padding: 12px;
  }

  .product-label {
    font-family: "Noto Sans", "Noto Sans CJK JP", sans-serif;
    font-size: 12px;
    margin: 10px;
  }

  .product-image {
    width: 160px;
    display: block;
    margin-left: auto;
    margin-right: auto;
  }
</style>

<!--Item content block-->
<div><img src="${item.imageUrl}" class="product-image" /></div>
<div class="product-label">彼らの機器や装置はすべて生命体だ。</div>
```

**important:** Personalization OTE templates _do not_ support multiple locales.

## See Also

- [Salesforce IdeaExchange](https://trailblazer.salesforce.com/ideaSearch?filter=Marketing+%3E+Interaction+Studio)

<!-- document id=4f0cdc7d639efc575307c9c67d1c015038f1a93100bf948695b6cbc3ec8f0b9f url=/developer/current/en-us/personalization/personalization/guides/campaign-development/server-side-campaigns-templates/sales-service-cloud-connector-einstein-decisions.md -->

# Sales/Service Cloud Connector - Einstein Decisions Template

The Marketing Cloud Personalization CRM Einstein Decisions template is designed for use alongside the Next Best Action component of the [connector for Sales and Service Clouds](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N4V00000GFjhsUAD). When configuring the template, code available below, it is important that you only modify the following parts:

- Maximum promotions returned

Any changes to the template outside the preceding areas could break the component's ability to render the response. As noted in the [business user documentation](https://help.salesforce.com/s/articleView?id=sf.mc_pers_salesforce_sales_service_cloud_connector.htm), impression, and click data is currently not sent back to Personalization Campaign from CRM.

## Prerequisites

To use the following server-side template, you need Personalization Connector for Sales and Service Cloud **version 2.0**. If you're unsure of your CRM package version, you can check your package version by doing the following.

1. Log into your Sales/Service Cloud account.
2. Navigate to the Setup page by clicking the gear icon in the top-right corner and then **Setup**.
3. In the left-hand navigation menu, select **Apps** > **Packaging** > **Installed Packages**.
4. Search for "Personalization Connector for Sales and Service Cloud".

The package version number is listed alongside the package name.

If you're running **version 1.5 or lower** or **version 1.8 or later**, you can upgrade your AppExchange package by navigating to the [connector AppExchange page](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3u00000OMyyQEAT), downloading the latest version, and then selecting **Upgrade for all users** when prompted.

If you're running **version 1.6 or 1.7**, you will have to uninstall your existing package and reinstall the latest version. After you've upgraded to version 2.0, you will not need to uninstall the package for future updates, as you will then become eligible for the upgrade option outlined for those users on version 1.5 or lower.

For instructions on upgrading your package, see [Install Personalization Connector for Sales and Service Cloud](https://help.salesforce.com/s/articleView?id=sf.mc_pers_salesforce_sales_service_cloud_connector_install.htm) on the Salesforce Help site.

## Server-Side Code

The following code sample contains Typescript code for the Personalization CRM Recommendations template.

```typescript
import { ContextualBanditConfig, decide } from "corvus";
import { ItemReference, ContentZoneLookup } from "common";

export class PromotionSearchOptions implements Search<string> {
  search(context: GearLifecycleContext, searchString: string): ItemReference[] {
    if (!searchString) {
      return [];
    }
    const promos: Promotion[] = context.services.catalog.findByName(
      "Promotion",
      searchString,
    ) as Promotion[];
    return promos.reduce((allPromos: ItemReference[], promo: Promotion) => {
      const promoItem = {
        itemType: "Promotion",
        id: promo.id,
        label: promo.attributes["name"] != null ? promo.attributes["name"].value : promo.id,
      } as ItemReference;
      allPromos.push(promoItem);
      return allPromos;
    }, []);
  }
}

export class EinsteinDecisionsTemplate implements CampaignTemplateComponent {
  @lookupOptions(() => new ContentZoneLookup())
  assetContentZoneOrTag: string;

  @searchOptions((self) => new PromotionSearchOptions())
  @title("Optional Fallback Promotion Selector")
  @subtitle(`Search for a fallback promotion to return if there are no eligible promotions to return for the end user.
   If no fallback is selected, no promotion will be returned. (NOTE: This field is case-sensitive.)`)
  fallbackArm: ItemReference;

  datafield: string = "promotions";
  run(context: CampaignComponentContext) {
    const banditConfig: ContextualBanditConfig = {
      maxResults: 3,
      contentZone: this.assetContentZoneOrTag,
      fallbackArms: this.fallbackArm ? [this.fallbackArm.id] : [],
    } as ContextualBanditConfig;
    return { [this.datafield]: decide(context, banditConfig, null) };
  }
}
```

<!-- document id=3b4b9fc66c6fe5652e7192db779eab80e5e4071f6f5f8821338fa56ed9e39076 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/server-side-campaigns-templates/server-side-next-best-recs-template.md -->

# Sales/Service Cloud Connector - Next Best Recommendations Template

The Marketing Cloud Personalization CRM Recommendations template is designed for use alongside the Next Best Recommendations component of the connector for Sales and Service Clouds. When configuring the template, it is important that you only modify the following parts.

- Maximum items returned
- Recommended `itemType` (`Product`, `Blog`, `Article`, and so on.)

Any changes to the template outside the preceding areas could break the component's ability to render the response. As noted in the [business user documentation](https://help.salesforce.com/s/articleView?id=sf.mc_pers_salesforce_sales_service_cloud_connector_server_side_campaign_next_best_offers.htm), impression, and click data is currently not sent back to Personalization Campaign from CRM.

## Prerequisites

To use the following server-side template, you need Personalization Connector for Sales and Service Cloud **version 1.8 or later**. If you're unsure of your CRM package version, you can check your package version by doing the following.

1. Log into your Sales/Service Cloud account.
2. Navigate to the Setup page by clicking the gear icon in the top-right corner and then **Setup**.
3. In the left-hand navigation menu, select **Apps** > **Packaging** > **Installed Packages**.
4. Search for "Personalization Connector for Sales and Service Cloud".

The package version number is listed alongside the package name.

If you're running **version 1.5 or lower**, you can upgrade your AppExchange package by navigating to the [connector AppExchange page](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3u00000OMyyQEAT), downloading the latest version, and then selecting **Upgrade for all users** when prompted.

If you're running **version 1.6 or 1.7**, you have to uninstall your existing package and reinstall the latest version. After you've upgraded to version 1.8, you will not need to uninstall the package for future updates, as you become eligible for the upgrade option outlined for those users on version 1.5 or lower.

For instructions on upgrading your package, see [Install Personalization Connector for Sales and Service Clouds](https://help.salesforce.com/s/articleView?id=sf.mc_pers_salesforce_sales_service_cloud_connector_install.htm) on the Salesforce Help site.

## Server-Side Code

The following code sample contains Typescript code for the Personalization CRM Recommendations template.

```typescript
import { RecommendationsConfig, recommend } from "recs";

export class ServerSideCRMRecTemplate implements CampaignTemplateComponent {
  /**
   * Developer Controls
   */

  @hidden(true)
  maximumNumberOfItems: 2 | 4 | 6 = 4;

  /**
   * Business-User Controls
   */

  datafield: string = "recs";

  @title(" ")
  recsConfig: RecommendationsConfig = new RecommendationsConfig()
    .restrictItemType("Product")
    .restrictMaxResults(this.maximumNumberOfItems);

  run(context: CampaignComponentContext) {
    this.recsConfig.maxResults = this.maximumNumberOfItems;

    return {
      itemType: this.recsConfig.itemType,
      serverSideMessages: [
        {
          dataMap: {
            [this.datafield]: recommend(context, this.recsConfig),
          },
        },
      ],
    };
  }
}
```

<!-- document id=5f3bd11febb410be8299853b2d97e7dc6c016aee5db4fd92d44c568b53fd62fa url=/developer/current/en-us/personalization/personalization/guides/data-analytics/scratch-schema.md -->

# Scratch Schema

The Personalization Data Warehouse supports the use of "scratch" tables for analysis, reporting, or investigation. In addition, scratch tables can be used as a data source by the Personalization ETL system. Using the ETL system and scratch tables, data scientists can load machine learning model scoring outputs from their data science workbench back into the Personalization production database to enrich user profile attributes. Customers can add and drop scratch tables in their data warehouse that follow the scratch schema specifications described in this article.

**note:** The Data Warehouse is available only to customers who have already purchased the Marketing Cloud Personalization - Data Warehouse add-on product.

## ETL Scratch Tables

The Data Warehouse scratch tables temporarily store Data Science workbench model score outputs for loading back into Personalization user profile attributes. Personalization Data Warehouse supports the ingestion of data written to customer's scratch schema. Tables in the scratch schema can be treated as data sources for the Personalization ETL system.

Multi-channel operation is enabled when user identities can be matched with the Personalization identity resolution system. Catalog data best support multi-channel operation when identities for online and offline product and dimension identities match.

## User Tables

Table Name Format: `schema_user_{token}_YYYYMMDD_HHMMSS`

Example: `retail_user_20200101_093000`. Optionally, you can include a descriptive token in the name: `retail_user_email06_20200101_090000`.

**note:** You must supply some form of user id, so at least one of the following optional user or email address fields is required to process a row.

To be able to process updates, include a `created_ts` field, as shown in the following table. This way, the ETL can process rows created since the last run. Instead of updating attributes in a scratch table, use a `DELETE` and an `INSERT` so that the `created_ts` field is reset, or include the `created_ts` in your `UPDATE`.

### Requirements and Schema

| Field Name      | Minimum Requirements                                                                                                                                                                                                                                                                                                                                    | Example Values                                               | Data Type                                                |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------- |
| `user_id`       | Optional. Must match the format of the configured default user ID type for this feed. Since a user can have multiple identities, user ids can also be constructed from other identifying information in the record (`email_address`, `attributes`, or other `user_id:` fields). If none of these methods result in a user ID, this record isn’t loaded. | `jdoe`, `john.doe@example.com`, `c2e384084c8ac233`           | VARCHAR(120)                                             |
| `user_id:`      | Optional. Column titles are the token `user_id` followed by a colon followed by the user ID type. Values must match the format of the specified user ID type. Otherwise, processed like `user_id`.                                                                                                                                                      | `"user_id:named": "jdoe"`, `user_id:marketo_id: "29237102"`  | VARCHAR(120)                                             |
| `account_id`    | Optional. If provided, a string value of the account ID to associate with the user. Must be lowercase. This field is only available with Personalization B2B functionality enabled. Contact your customer success representative for details.                                                                                                           | example industries, example.com                              | VARCHAR(120)                                             |
| `display_name`  | Optional. Display name for user.                                                                                                                                                                                                                                                                                                                        | Bob Newhart                                                  | VARCHAR(1023)                                            |
| `email_address` | Optional. Valid email address. If provided, used as a user identity of the type `emailAddress`.                                                                                                                                                                                                                                                         | user@example.com, bob.smith@example.com                      | VARCHAR(1023)                                            |
| `attribute:`    | Optional. The custom attributes for this user. Column titles are the word `attribute` followed by a colon followed by the attribute name. Attributes are singled-valued and always interpreted as strings. Attributes can be used to construct user IDs.                                                                                                | `"attribute:lastname": Gina`, `"attribute:firstname: Torres` | VARCHAR(1023)                                            |
| `created_ts`    | **Required.** Records when the row was created.                                                                                                                                                                                                                                                                                                         |                                                              | TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT `getdate()` |

<!-- document id=28528ba084a94d17e873bf1707e02b3173602927df10d6da4a7a6b67fbf2bddb url=/developer/current/en-us/personalization/personalization/guides/custom-interface-template-configuration/properties/select.md -->

# Select Property

## Basic Dropdown

See Enumerated values within [String](https://developer.salesforce.com/docs/marketing/personalization/guide/string.md) and [Number](https://developer.salesforce.com/docs/marketing/personalization/guide/number.md).

---

## Complex Types As Option Values

Static values for complex configurations can be defined such that they appear as options within a dropdown menu by using the `@options` decorator. If the complex type contains a `label` property, it is used for the option's label.

```typescript
export class ComplexType {
  firstProperty: string;
  secondProperty: number;
  label: string;
}

export class SimpleTemplate implements CampaignTemplate {
  @options([
    { firstProperty: "one", secondProperty: 1, label: "First Option" },
    { firstProperty: "two", secondProperty: 2, label: "Second Option" },
  ])
  myOptionProperty: ComplexType;
}
```

![Complex Dropdown](https://developer.salesforce.com/media/interface-template-configuration/ComplexSelect.png)

---

## Simple Dynamic Option Values

Dynamic options can be loaded using the `@lookupOptions` decorator. If the options value is a string, the value is used as the label.

```typescript
export class ItemTypeLookup implements Lookup<string> {
    lookup(context: GearLifecycleContext): string[] {
        return context.services.config.findEnabledItemTypes();
    }
}

export class SimpleTemplate implements CampaignTemplate {}
    @lookupOptions(() => new ItemTypeLookup())
    itemType : string;
}
```

![Dynamic Dropdown](https://developer.salesforce.com/media/interface-template-configuration/DynamicSelect1.png)

---

## Dynamic Option Values

If the class has a `label` property, this property is displayed in the dropdown.

```typescript
export class SegmentReference {
  value: string;
  label: string;
}

export class SegmentLookup implements Lookup<SegmentReference> {
  lookup(context: GearLifecycleContext): SegmentReference[] {
    let segments = context.services.config.findSegments("User");

    return segments.map((segment) => {
      return <SegmentReference>{ value: segment.id, label: segment.name };
    });
  }
}

export class SimpleTemplate implements CampaignTemplate {
  @lookupOptions(() => new SegmentLookup())
  segment: SegmentReference;
}
```

![Dynamic Dropdown](https://developer.salesforce.com/media/interface-template-configuration/DynamicSelect2.png)

---

## Dynamic Option Values With Configuration

The `Lookup` class can pass data via a constructor to configure what the lookup method returns as options.

```typescript
type CustomerType = "User" | "Account";

export class SegmentReference {
  value: string;
  label: string;
}

export class SegmentLookup implements Lookup<SegmentReference> {
  customerType: CustomerType = "User";

  constructor(customerType: CustomerType) {
    this.customerType = customerType;
  }

  lookup(context: GearLifecycleContext): SegmentReference[] {
    if (!!this.customerType) {
      let segments = context.services.config.findSegments(this.customerType);

      return segments.map((segment) => {
        return <SegmentReference>{ value: segment.id, label: segment.name };
      });
    }
  }
}

export class SimpleTemplate implements CampaignTemplate {
  customerType: CustomerType;

  @lookupOptions((self) => new SegmentLookup(self?.customerType))
  segment: SegmentReference;
}
```

![Dynamic Dropdown](https://developer.salesforce.com/media/interface-template-configuration/DynamicSelect3.png)

---

## Searchable Options

The `@searchOptions` decorator works similarly to `@lookupOptions`. The difference is that `@searchOptions` provides a search string that can be used to filter applicable options.

```typescript
export class CityReference {
  value: City;
  label: string;
  searchString: string;
}

export class CitySearch implements Search<CityReference> {
  search(context: GearLifecycleContext, searchString: string): CityReference[] {
    if (searchString) {
      let cities: City[] = context.services.geography.searchCities(searchString);
      return cities.map((c) => {
        return <CityReference>{ label: c.longName(), value: c };
      });
    }
  }
}

export class SimpleTemplate implements CampaignTemplate {
  @searchOptions(() => new CitySearch())
  city: CityReference;
}
```

![Dynamic Dropdown](https://developer.salesforce.com/media/interface-template-configuration/DynamicSelect4.png)

<!-- document id=e860753191c7e3d0b54d1e2f93b76fd74e1b99024e8875ff1a8ac36879901592 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/templates/send-web-campaign-statistics-third-parties.md -->

# Sending Campaign Statistics to Third Parties

With Marketing Cloud Personalization, you can gain valuable insights into the performance of your Personalization campaigns. By analyzing impressions, clickthrough rates, dismissals, and recommended items, you can make informed decisions on optimizing your campaigns for better results. This data helps you increase the effectiveness of your campaigns and achieve your goals.

In addition to using Personalization campaign statistics, many organizations find using third-party analytics software to track campaign effectiveness helpful. This article outlines how to access campaign statistic event data from Personalization. You can use this method to format events for third-party tracking systems like Google Analytics and Adobe Analytics.

When tracking campaign statistics, whether using the [Campaign Stats Gear](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-stats-tracking.md) or not, the `OnStatSend` custom event is triggered and includes the following information.

```typescript
{
  campaignStat: CampaignStat;
  campaignResponse: CampaignResponse;
}
```

The `campaignStat` object is the actual statistic tracked by Personalization. The `campaignResponse` object contains all the data returned from the server for the associated campaign in the `campaignStat`. The `campaignResponse` object has the following structure.

```typescript
{
  campaignId: string;
  campaignJavascriptContent: string;
  campaignName: string;
  campaignType: string;
  experienceId: string;
  experienceName: string;
  experienceSourceCode: string;
  payload: {};
  state: string;
  templateNames: string[];
  type: string;
  userGroup: string;
};
```

The following code snippets illustrate how to listen for the `OnStatSend` custom event in a Personalization sitemap.

```javascript
const storedCampaignStats = [];
document.addEventListener(SalesforceInteractions.mcis.CustomEvents.OnStatSend, (event) => {
  const isThirdPartyLoaded = false;

  const statType = event.detail.campaignStat.stat;
  const isControl = event.detail.campaignStat.control;
  const campaignId = event.detail.campaignResponse.campaignId;
  const experienceId = event.detail.campaignResponse.experienceId;

  if (isThirdPartyLoaded) {
    // send campaign stat to third party
  } else {
    // store campaign stat to send later when third party loaded
    storedCampaignStats.push({ statType, isControl, campaignId, experienceId });
  }
});
```

```javascript
const storedCampaignStats = [];
document.addEventListener(Evergage.CustomEvents.OnStatSend, (event) => {
  const isThirdPartyLoaded = false;

  const statType = event.detail.campaignStat.stat;
  const isControl = event.detail.campaignStat.control;
  const campaignId = event.detail.campaignResponse.campaignId;
  const experienceId = event.detail.campaignResponse.experienceId;

  if (isThirdPartyLoaded) {
    // send campaign stat to third party
  } else {
    // store campaign stat to send later when third party loaded
    storedCampaignStats.push({ statType, isControl, campaignId, experienceId });
  }
});
```

## See Also

- [Tracking Personalization Web Campaign Statistics](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-stats-tracking.md)
- _Salesforce Help_: [Reports and Analytics](https://help.salesforce.com/s/articleView?id=sf.mc_pers_report_analytics.htm)

<!-- document id=d22195d4f038c7d599b0d975d033699575a3184924a071fcba0a8da67fd877af url=/developer/current/en-us/personalization/personalization/guides/campaign-development/server-side-campaigns-templates/server-side-campaigns-content-zones.md -->

# Server-Side Campaigns and Content Zones

The key difference between server-side campaigns and web campaigns is that server-side campaigns do not require Content Zones. As a result, the server-side template configurator does not have the Content Zone selector pane.

The following sections describe the differences in how Content Zones are used for web and server-side campaigns.

## Web Campaigns

Web campaigns require the Content Zone selector since Marketing Cloud Personalization is responsible for rendering the campaign.

- A template developer can assign one or more Content Zones to templates to determine where a particular template can be used on the site by a business user.
- A business user targets a campaign to a specific Content Zone on the site and can then apply published templates that were tagged with that Content Zone by their template developer.

By linking web templates to specific Content Zones, a template developer ensures that Personalization renders the experience correctly, as the template was designed to work on that particular part of the site.

## Server-side Campaigns

In a server-side campaign execution, the client takes responsibility for rendering the response payload returned by Personalization. Since the output of a server-side campaign is simply a data payload, template creation or campaign targeting do not require Content Zone selection. In a server-side campaign execution, it is up to the client to:

- determine what data must be passed back as part of the campaign response (defined in server-side template)
- apply the template to a campaign with appropriate targeting logic (Server-Side Campaign)
- call Personalization's Event API and take the data it returns in the campaign response object and render it in the correct location/format

Clients that have implemented the Personalization Web SDK (with content zones defined in the sitemap) and are using server-side campaigns to power personalized experiences can leverage Content Zones to tie a server-side campaign to a specific location on the site. Much like how a web campaign is returned if the Content Zone is present on the page, a server-side campaign that uses Content Zone targeting is also returned only if the targeted Content Zone is present in the request. Adding a Content Zone to your server-side template only requires a basic adjustment to the server-side code (the Content Zone selector pane used for web campaigns is not available for Server-Side campaigns).

In the server-side code, add the line `contentZone: "contentZone1" | "contentZone2"...`. Adding one or more Content Zone options will create the Content Zone dropdown selector in the business user template configurator. The template developer decides the number of Content Zones for which a template is eligible.

After you add a Content Zone to a server-side template, you must ensure that you configure your API calling patterns correctly. Specifically, you need to have `contentZones` included on the source object in the Event API request. A template with a `contentZone` applied will only be returned in the response if its targeted `contentZone` is present in the Event API request.

**important:** Personalization returns only one campaign response per `contentZone`. Therefore, if you have two campaigns targeting the same `contentZone` and the user is eligible for both, only one campaign is returned. A business user can easily prioritize which campaign returns by assigning a priority value to the campaign in the campaign configuration screen. As noted by the info icon next to the priority input box (found in the **Campaign Type** window of the campaign creation screen), campaigns with a higher numeric priority takes precedence. If campaigns share a priority value, the campaign that was created first wins.

The ONLY time a Content Zone requires a value in the server-side code as part of a server-side campaign is for promotion selection/decisioning purposes. Einstein Decisions requires that a Content Zone or tag is defined to filter which promotion assets are eligible to be returned as part of the campaign response. The Content Zone or tag you want to use as part of the Einstein Decisions template would need to be hardcoded into the server-side template code.

**important:** When previewing a server-side template in the in-app template editor, the `contentZone` field in the **Payload Preview** shows a `NULL` value even if you have a `contentZone` applied in the code or selected in the template configuration. However, the selected/applied Content Zone works as desired when the template is applied to a campaign, as that `NULL` value in the simulator does not indicate that anything is wrong with the template.

### Example Server-side Template with Content Zones

The following code sample is an example of a server-side template with Content Zones configured.

```typescript
import { RecommendationsConfig, recommend } from "recs";

export class EinsteinProductRecsTemplate implements CampaignTemplateComponent {
  /**
   * Developer Controls
   */

  /**
   * The below line illustrates how to add content zones or tags to a server-side template. If more than one is added, it will create the content zone drop-down in the business user config.
   */
  contentZone: "home_recs" | "product_detail_recs_row_1";

  @hidden(true)
  maximumNumberOfProducts: 2 | 4 | 6 | 8 = 4;

  @hidden(true)
  maxRatingBound: number = 5;

  /**
   * Business-User Controls
   */
  @title("Recommendations Block Title")
  header: string = "Title Text";

  @title(" ")
  recsConfig: RecommendationsConfig = new RecommendationsConfig()
    .restrictItemType("Product")
    .restrictMaxResults(this.maximumNumberOfProducts);

  run(context: CampaignComponentContext) {
    this.recsConfig.maxResults = this.maximumNumberOfProducts;

    return {
      itemType: this.recsConfig.itemType,
      products: recommend(context, this.recsConfig),
    };
  }
}
```

### Example Event API Request for a Server-Side Campaign Leveraging Content Zones

The following is an example Event API request for a server-side campaign that leverages Content Zones.

```json
{
  "action": "action",
  "user": {
    "id": "sample user"
  },
  "source": {
    "channel": "Server",
    "contentZones": ["home_recs", "product_detail_recs_row_1"]
  }
}
```

<!-- document id=dc609c60b70f2a30199763f04434a3c59caa28488bc73b74232a993387a16f1b url=/developer/current/en-us/personalization/personalization/guides/campaign-development/server-side-campaigns-templates.md -->

# Server-Side Campaigns and Templates

Marketing Cloud Personalization allows business users to build server-side campaigns and templates using a streamlined version of the web templates editor and the same campaign builder that you are familiar with from web campaigns. By leveraging the same campaign builder and the same underlying template infrastructure, clients can more easily extend campaigns across channels and even build a single campaign that multiple applications can call. Server-side campaigns are available to Premium Edition clients.

## Log in to Personalization

1. Log in to your Personalization Account.
2. Navigate to the dataset where you want to build your server-side campaign.

## Create a New Server-Side Campaign

1. Select **Server-Side** from the left-hand navigation in the **Channels & Campaigns** section. Doing so takes you to a screen where you can view all of your published & disabled server-side campaigns. (Published campaigns have bolded names. Names of unpublished campaigns are not bolded.)
2. To create a campaign, click **New Campaign**.

   a. When you create a new server-side campaign, it will open the campaign interface and have a campaign targeting rule of `channel: Server` applied by default.

   **important:** The campaign level `channel: Server` rule means that by default, a server-side campaign requires the `/authevent` API endpoint and an API token to return a response.

   b. Campaign targeting rules are configurable by the business user. For more information about channel targeting, see [Campaign Targeting and Experience Rules](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_rule.htm).
   **note:** Creating a new server-side campaign using the Classic editor is no longer supported for clients leveraging the campaigns & templates system. If you have existing server-side Classic campaigns, they continue to function and you can still access and edit those campaigns, but you cannot create a new one.

   ![Template screen](https://developer.salesforce.com/media/campaign-development/template-screen.png)

**note:** Both rule-based and A/B tests provide options for a control experience. With A/B tests, you determine control traffic using a slider. With rules-based campaigns you enter a control percentage in an input field.

## Determine the Campaign Type

There are two campaign types. A/B Test campaigns split traffic randomly into different groups based on percentages you define. Each group sees a different campaign experience. Rule-Based Test campaigns follow the rules you define to determine which experience to show to each visitor. For example, using a rule-based test, you could target a segment of visitors who had not been to your site in 30 days and show them experience 1, then show experience 2 to visitors who had been to your site in the last 24 hours.

The default campaign type in the campaign interface is _A/B Test_. To change the campaign type, do the following.

1. Click **>** next to **A/B Test**.
2. Choose the campaign type that supports your goal for the campaign.

   a. [A/B Test](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_create.htm)
   b. [Rule-Based Test](https://help.salesforce.com/s/articleView?id=sf.mc_pers_web_campaign_rule_based_test.htm)

3. Toggle between **A/B Test** and **Rule Based Test** to change the type.

## Create and Name Campaign Experiences

Determine how many experiences you want to have for your campaign. If you'd like to deliver a different campaign experience to various groups of qualified visitors, create additional experiences by cloning the configured experience. You can then modify the next experience using the same template or apply a different template as needed.

To create campaign experiences, do the following.

1. Still in **Campaign Type**, click the following icon to clone an experience.
   ![The clone icon](https://developer.salesforce.com/media/campaign-development/clone-icon.png)
2. Double-click the **Experience Name** to rename the experience.
3. Repeat the cloning and renaming process until you have the desired number of experiences for your campaign.

**note:** - The name of each experience shows up in your campaign statistics report. It can be helpful to name each experience with what is unique about that experience so you can interpret the results in reporting. For example, if you are building a cross-channel campaign, it is helpful to name each experience with their respective channel name. For example, you can name your experiences Mobile, POS, Web, and so on, depending on their channel.
- For rules-based campaigns, if a user that qualifies for a campaign also qualifies for multiple experiences, the experience higher in the list of experiences is considered the higher priority experience. You can drag and reorder campaign experiences on the campaign type screen.

## Determine Campaign Identity & Authentication Requirements

Server-side campaigns have the same targeting options available as web campaigns. There are, however, important nuances around the channel rule that have identity and authentication implications. As described in the previous section, server-side campaigns have the campaign-level targeting logic of `channel: Server` applied by default.

**note:** While a business user can choose to remove this logic, its inclusion means that the campaign requires an authenticated request via the `/authevent` endpoint with channel set to `Server` in the call in order to return a campaign response.

Additional information around the implications for using or removing the `channel: Server` logic is as follows:

- **Authenticated Campaigns:**

  - **channel: Server Rule:**

    - **Authentication:** Whenever `channel: Server` is present (at either the campaign level or experience level), Personalization requires authentication to return a campaign response, as `Server` is a default "Trusted" channel. _(If your Personalization account was provisioned before **1/28/2021**, file a support ticket to get `channel: Server` added as a trusted channel)_
    - **API Calling Pattern:** The inbound request that includes `channel: Server` MUST leverage the `/authevent` endpoint and include an API token. If a POST request is made to the `/authevent` endpoint without either `channel: Server` or an API token included, no campaign response data is returned.

      For more information on `/authevent` and generating an API token, refer to the [Authenticated Event Endpoint](https://developer.salesforce.com/docs/marketing/personalization/event-api/event-api-requests.md#authenticated-event-endpoint) and the [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm) articles.

    - **Identity:** When `channel: Server` is applied to a POST request that goes through the `/authevent` endpoint, there are two potential identity configuration options (outlined in detail in this article) that determine how a user is referenced. These two identity configuration options are outlined in detail by the following illustrations.
      ![Template Flowchart](https://developer.salesforce.com/media/campaign-development/template-flowchart.png)

- **Unauthenticated Campaigns:**

  - **channel: Web Rule**
    - **Authentication:** If the default `channel: Server` campaign level rule is removed, you can update a user and get campaign responses returned without authentication.
    - **API Calling Pattern:** The inbound request that includes `channel: Web` MUST leverage the `/event` endpoint. If a POST request is made to the `/event` endpoint with no channel value or a different channel value included, you cannot reference an identity attribute and could end up creating new users in the platform. For more information on the `/event` endpoint, refer to the [Event API](https://developer.salesforce.com/docs/marketing/personalization/event-api/event-api.md) documentation.
    - **Identity:** When `channel: Web` is applied to an inbound request that goes through the `/event` endpoint, the value provided for `user.id` references the Web SDK identity attribute that is configured via the **Identity Settings** screen. To facilitate additional profile merge scenarios, you can include more than one identity attribute in the `user.attributes` object. Do remember that this behavior is different from when using the `/authevent` endpoint.

- **Hybrid Authenticated & Unauthenticated Campaigns:**

  - While A/B/n testing campaigns can ONLY be either fully authenticated or unauthenticated, rules-based campaigns provide additional flexibility via experience level rules. By removing the default campaign level `channel: Server` rule, you can make certain experiences within a campaign either require or not require authentication. To do so, simply apply either `channel: Server` or `channel: Web` as a rule on the experience.
    **important:** - If you decide to mix `channel: Web` & `channel: Server` logic into a single campaign, ensure that you use the correct endpoints and ID values in the call for the respective experiences.
    - If you include a channel value in the campaign targeting logic that is not either `Web` or `Server`, you will NOT be able to access identity attributes in the campaign. `Web` and `Server` are the only channel values with identity support.

## Create Application Specific Experiences

There are a couple different ways for a user to build a single Server-Side campaign that can power experiences across multiple touch-points.

- **Restrict campaign response to certain applications at the campaign level:** If you want to limit a campaign response to only certain applications, you can layer in additional targeting rules via the **Source → Application** rule. By applying this rule, an inbound request needs to include one of the applications listed on the campaign rule (for example, Mobile, POS, Support) for a response to be returned. This type of targeting helps ensure you are only returning campaign responses relevant to that particular application.
- **Application-specific experiences:** If you want to build different experiences for different applications, a business user would leverage a rule-based campaign and apply application targeting logic to the experience. To apply application targeting logic, apply an application rule at the experience level (for example, Mobile or POS). The application is required in the inbound call to return the experience designed for that specific application.

  ![A sample campaign configuration](https://developer.salesforce.com/media/campaign-development/campaign-configured.png)

## Apply a Template

After you have created a campaign, named it, and applied your targeting logic, it's time to apply a template. To apply a template, do the following.

1. Under your first experience, click **Add Template**.
2. The **Select Template** window displays all published server-side templates. Select the template that you'd like to apply.

After it is selected, the template name will appear under the experience, and the business user can fill in the configuration options that you've exposed.

## Test Experiences

To test a server-side campaign that is built from a template, you need to use a tool to make POST requests. For campaigns that require authentication, you need access to an API token. The campaign response generated by Personalization is the same format as the response generated for web campaigns using the campaign and templates system. If you are unsure about the validity of your API Token, review it with your Personalization account administrator. For more information, see [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm).

1. Create an API **POST** request. Depending on your campaign's authentication type, use either of the following POST endpoints.

   - **Authenticated:** `/api2/authevent/{dataset}`
   - **Unauthenticated:** `/api2/event/{dataset}`
   - Testing a campaign or experience where `channel: Server` is included requires an API token to return a response. By default, a server-side campaign has `channel: Server` configured in the campaign targeting logic meaning campaign responses return only for authenticated requests. (If you removed the `channel: Server` logic, you need to reference the `/event` endpoint for unauthenticated posts/responses).

2. If using the `/authevent` endpoint, you need to leverage **Basic Auth** & enter your API token credentials your Key is the **Username** and the Secret as the **Password**.
3. The **Body** content of the request must be constructed as **JSON**.
4. You can submit the following two types of test requests. Sample calls that you can copy and paste are available in the next section.

   - `testMessages: experienceId`: In this configuration, you would replace the `experienceId` text with the ID of the campaign experience you are looking to test (see image on the right to learn how to find your campaign experience ID). Testing in this manner will IGNORE campaign rules, but allows you to validate the campaign response data looks correct. By including a specific `experienceId`, you ARE able to test an unpublished campaign experience. Testing a specific experience can ONLY be done via the `/authevent` endpoint. Therefore, if you have an unauthenticated campaign leveraging the `channel:Web` rule, in order to test the campaign response for a specific experience while the campaign is unpublished, you still need to use `channel:Server` in the POST.
   - `testMessages: experienceId`: In this configuration, you would replace the `experienceId` text with the ID of the campaign experience you are looking to test (see the following image to learn how to find your campaign experience ID). Testing in this manner will IGNORE campaign rules, but allows you to validate the campaign response data looks correct. By including a specific experience ID, you ARE able to test an unpublished campaign experience. Testing a specific experience can ONLY be done via the `/authevent` endpoint. Therefore, if you have an unauthenticated campaign leveraging the `channel:Web` rule, in order to test the campaign response for a specific experience while the campaign is unpublished, you still need to use `channel:Server` in the POST.

   ![Finding a campaign's experience ID](https://developer.salesforce.com/media/campaign-development/finding-campaign-experience-id.png)

   **note:** When testing campaigns using the `testMessages` parameter, the [Campaign Stats Gear](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/campaign-stats-tracking.md) still tracks campaign statistics even if the campaign you're testing is not published.

### Sample authevent API POST Request (Default Identity Configuration)

```json
{
  "action": "sample",
  "user": {
    "attributes": {
      "emailAddress": "test@test.com",
      "customerId": "123456789"
    }
  },
  "source": {
    "channel": "Server",
    "application": "POS"
  }
}
```

### Sample authevent API POST Request (Event API Identity Attribute Assigned)

```json
{
  "action": "hello world",
  "debug": {
    "testMessages": "true"
  },
  "user": {
    "id": "sampleuserid"
  },
  "source": {
    "channel": "Server"
  }
}
```

**note:** The ID value you select for a user looks for a user in the system based on the identity attribute that you have assigned to the Event API. For instructions and information on selecting the identity attribute for the Event API, see [Configure the Identity System for the Event API](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity_event_api.htm&type=5).

### testMessages: experienceId

To find your campaign's experience ID, simply open the Server-Side campaign list screen, select the campaign you are intending to test and scroll down to the **Overview** section. The experience ID is listed next to the eye icon on the right side of the page, as highlighted in the following screenshot.

![Viewing a Campaign's Experience ID](https://developer.salesforce.com/media/campaign-development/experience-id-demo.png)

In order to test a specific experience, a trusted channel MUST be included in the call. Doing so ensures that ignoring campaign rules does not ignore authentication requirements.

#### Sample authevent API POST Request (Default Identity Configuration)

```json
{
  "action": "hello world",
  "debug": {
    "testMessages": "experienceId"
  },
  "user": {
    "attributes": {
      "emailAddress": "test@test.com",
      "customerId": "123456789"
    }
  },
  "source": {
    "channel": "Server"
  }
}
```

#### Sample authevent API POST Request (Event API Identity Attribute Assigned)

```json
{
  "action": "hello world",
  "debug": {
    "testMessages": "experienceId"
  },
  "user": {
    "id": "sampleuserid"
  },
  "source": {
    "channel": "Server"
  }
}
```

## Publish the Campaign

After you have thoroughly tested your campaign, you need to publish it to make it live. The process for publishing a campaign can be done on the campaign list page or while editing the campaign.

1. While editing your campaign in the campaign editor, save your changes.
2. The SAVE button becomes unavailable indicating that all changes have been saved.
3. Slide the toggle to **PUBLISHED**.
4. You receive a confirmation message stating that the campaign was published
5. To disable a campaign, slide the toggle to **DISABLED**.
6. You receive another confirmation message stating that the campaign was unpublished.

**tip:** **Campaign Access Controls:** To know who has access to create, edit, or publish a campaign, review their user roles on Personalization. Roles-based access is a great way to ensure that campaigns go through the proper approval process before publishing for live traffic. Server-Side campaign & template creation follows the same permissions associated with web campaigns & templates.

## Track Campaign Results

To track campaign stats on a Server-Side campaign, you need to work with your web developer to pass stats information like impressions, clicks, and items returned back via the Personalization Event API. Those stats then appear in the campaign statistics report that is automatically generated for the campaign. For more information on how to pass campaign stats back to Personalization, refer to the [Campaign Stats Tracking](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/campaign-stats-tracking.md) documentation.

<!-- document id=bacff881f852cd834bb2430f0f13b6053392c473ee2b10d64e436c237e97e7ed url=/developer/current/en-us/personalization/personalization/guides/web-integration/sitemap-event-validation.md -->

# Sitemap Event Validation

A Sitemap sends events to Personalization based on the actions of the website visitors (users). There are several ways to validate whether the Sitemap configuration correctly recognizes the targeted user actions and sends the corresponding events.

## Sitemap Events

Sitemap events are HTTP requests sent to the Personalization Event API endpoint to describe either a web page's context or a specific user action performed on the site. Examples of Sitemap events include:

- Visiting a page
- Viewing a catalog item
- Submitting a form
- Adding an item to a shopping cart
- Purchasing an item
- Clicking a designated page area

## Sitemap Event Validation Tools and Methods

You can validate Sitemap events using these tools and methods.

- [Personalization Sitemap Editor](#event-validation-using-the-sitemap-editor)
- [Personalization Event Stream Report](#event-validation-using-the-event-stream-report)
- [Chrome Browser Developer Tools](#event-validation-using-chrome-browser-developer-tools)

## Event Validation Using the Sitemap Editor

As you develop a Sitemap, you can use the Sitemap Editor to confirm whether the JavaScript describing your events is valid and configured correctly.

While the Sitemap Editor is vitally useful for the development process, it’s essential to test your sitemap code using the other methods outlined in this article. The Sitemap Editor initializes the sitemap code after the website it’s running on is fully loaded. Therefore, you can’t use the Sitemap Editor to test the real-world timing of initializing the sitemap while the page is still loading. Make sure to test the real-world timing on sitemap initialization outside the Sitemap Editor by monitoring the events sent by your sitemap as you browse the website using the event validation techniques outlined in this topic.

- [Event Validation Using the Event Stream Report](#event-validation-using-the-event-stream-report)
- [Event Validation Using Chrome Browser Developer Tools](#event-validation-using-chrome-browser-developer-tools)

### Sitemap JS Tab Code Check

On the **Sitemap JS** tab, where you enter your Sitemap JavaScript, a built-in code validator identifies JavaScript syntax errors, as shown in this image.

![Sitemap JS Code Errors](https://developer.salesforce.com/media/sitemap-js-code-errors.png)

The **Logs** tab provides messages related to the JavaScript code errors flagged by the Sitemap JS code editor. However, it’s advisable to use a more robust JavaScript validation tool to investigate JavaScript syntax issues and code execution errors flagged in the Sitemap JS code editor.

### Current Page Object Validation

This image shows the **Current Page** tab of the Sitemap Editor.

![Sitemap JS Code Errors](https://developer.salesforce.com/media/sitemap-current-page-objects-empty.png)

The **Current Page** tab displays all Sitemap objects configured and executed on the current page shown in the browser, including:

- **Page Type:** Name of the configured page type of the currently displayed page
- **User Data:** The ID of the current user browsing the page and any user-triggered events configured on the page. The user ID can be the user ID that is randomly generated for anonymous site visitors, or a named user ID.
- **Catalog Data:** Names of Catalog objects configured on the current page.
- **Content Zones:** Names of Content Zone objects configured on the current page.
- **DOM Listeners:** Names of JavaScript DOM listeners configured on the current page.

#### Current Page Object Examples

This image shows an example of how Sitemap objects appear in the **Current Page** tab with key functional areas indicated by numbers.

![Sitemap Current Page Objects](https://developer.salesforce.com/media/sitemap-current-page-objects-populated_markup-w720px.png)

This table lists the areas numbered on the figure and describes the purpose and function of each area.

| Number | Area                          | Description                                                                                                                                                                                                                                                                                                                                                                       |
| ------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **1**  | Current Page (Site Home Page) | This area displays the current page of the target site that the Sitemap editor is targeting. The objects displayed in the Current Page tab are configured for the page type displayed here. In the preceding example, the browser used by the Sitemap editor is on the Home page of the target site and has a `pageTypes` object called `home` configured in the Sitemap (**9**). |
| **2**  | Execute (button)              | Clicking the **Execute** button runs and validates the JavaScript in the Sitemap JS editor. Sitemap objects that resolve with the current page type or global configuration are displayed in the **Current Page** tab. Objects with invalid JavaScript don’t appear in the **Current Page** tab.                                                                                  |
| **3**  | Page Type                     | This area displays the page type that matches the results of the `isMatch` function configured for the currently displayed page type. In the preceding example, the site **Home** page type (**1**) is matched by the `isMatch` function configured for the page type named `home` in the Sitemap (**9**).                                                                        |
| **4**  | User Data                     | This area displays the user ID of the user visiting the current page and any user-triggered events configured in the Sitemap. The preceding example shows an anonymous user ID.                                                                                                                                                                                                   |
| **5**  | Catalog Data                  | This area displays any `catalog` objects configured in the **Sitemap JS** for the currently displayed page. In the preceding **Home** page example, no `catalog` objects have been configured.                                                                                                                                                                                    |
| **6**  | Content Zones - Global        | The preceding example shows that this Sitemap has two global Content Zones that are properly configured to show in the **Current Page** tab. Global content zones are active in all configured page types.                                                                                                                                                                        |
| **7**  | DOM Listeners                 | The preceding example shows that this Sitemap has a `listener` in the global configuration that is configured to show in the **DOM Listeners** section of the **Current Page** tab. This `listener` sends an event to Personalization when a user signs up for an email subscription.                                                                                             |
| **8**  | Content Zones - Page Type     | The preceding example shows that this Sitemap has three Content Zones that are properly configured to show in the **Current Page** tab when the Sitemap editor is on the `home` page type.                                                                                                                                                                                        |
| **9**  | pageTypes: `home`             | The preceding example shows that this Sitemap has a `home` page type configured to display in the **Page Type** section of the **Current Page** tab (**3**) when the Sitemap editor is on the `home` page type.                                                                                                                                                                   |

### Page Match Validation

The **Page Matches** tab displays the currently matched page type as well as all other page types configured in the Sitemap. The currently matched page displays with a "checkmark" while the other configured page types show with a "backslash" to indicate they weren’t matched as the current page.

This image shows an example of the **Page Matches** tab where the **home** page is the currently matched page as well as several other pages configured in the Sitemap JS editor but aren’t matched as the current page.

![Page Matches in Sitemap](https://developer.salesforce.com/media/sitemap-page-matches-w720px.png)

## Event Validation Using the Event Stream Report

The Personalization **Event Stream** report displays all events received by Personalization, including events sent from the Sitemap as well as from other sources.

### Accessing the Event Stream Report

To access the **Event Stream** report, carry out these steps.

1. Log in to the Personalization UI.

   ![Personalization Login Page](https://developer.salesforce.com/media/salesforce-interaction-studio-login.png)

2. On the **Dashboard**, use the dataset dropdown to select the dataset that contains the events you want to see.

   ![Selecting the dataset](https://developer.salesforce.com/media/salesforce-interaction-studio-select-dataset.png)

3. Hover over **Reports** on the sidebar to show the reports popup, and click **Event Stream** from the **Activity** section.

   ![Accessing the Event Stream Report](https://developer.salesforce.com/media/salesforce-interaction-studio-accessing-event-stream.png)

### Example: Event Processing and Display in the Event Stream

The Sitemap JavaScript sends events to Personalization based on actions performed by site visitors. This section presents an example based on an anonymous user who decides to sign up for emails from the company (thus becoming "known") and then browses the Men's section of the website.

#### JavaScript Listener for Email Sign-Up

Here's an example of a JavaScript listener configured to send an event when a user signs up for emails. Since the sign-up form appears on the bottom of every page on the site, make sure that you configure this listener as part of the `global` configuration.

```javascript
listeners: [
  SalesforceInteractions.listener("submit", ".email-signup", () => {
    const email = SalesforceInteractions.cashDom("#dwfrm_mcsubscribe_email").val();
    if (email) {
      SalesforceInteractions.sendEvent({
        interaction: { name: "Email Sign Up - Footer" },
        user: { identities: { emailAddress: email } },
      });
    }
  }),
];
```

```javascript
listeners: [
  Evergage.listener("submit", ".email-signup", () => {
    const email = Evergage.cashDom("#dwfrm_mcsubscribe_email").val();
    if (email) {
      Evergage.sendEvent({
        action: "Email Sign Up - Footer",
        user: { id: email },
      });
    }
  }),
];
```

#### Site UI for Email Sign-Up

Here's an example of a site email sign-up form completed by "Joe Customer". With the JavaScript listener configured as shown in the preceding section, an event is sent to Personalization and shows up in the **Event Stream** when a user provides their email address and clicks the submit button (**->**).

![Email Sign-Up Form](https://developer.salesforce.com/media/sitemap-email-signup-w640px.png)

#### Events Displayed in the Event Stream Report

If the email sign-up listener is properly configured in the Sitemap, when "Joe Customer" provides their email and clicks **Submit**, the event shows up immediately in the Personalization Event Stream report. Within the Event Stream report, you can:

- Search through the event stream
- Review data in an event stream table
- Access specific details for each event

This figure shows an example of the events sent to Personalization before and after Joe Customer submitted their email in the email sign-up form. These sections describe the information and functionality provided by the Event Stream report.

**note:** For more information about the available functionality in the Event Stream report, see [Event Stream Report](https://help.salesforce.com/s/articleView?id=mktg.mc_pers_report_activity_event_stream.htm).

![Viewing Event Details](https://developer.salesforce.com/media/salesforce-interaction-studio-viewing-event-details.png)

**note:** At this time, the Personalization Event Stream doesn't display `price` for `AddToCart` events.

**Event Stream Search**

In the Event Stream search area, you can search for and filter the Event Stream table to show only events generated by a specific user ID/username or email address. To search through the Event Stream, perform these steps.

1. In the **keyword** field, enter text that matches characters in the username or email address for the user whose events you want to see.

   The matching username shows as soon as you enter characters that match an existing username or email address.

2. Select the user. The Event Stream table then shows events for that user.
3. To view events of a specific type only, select the event type from the **Event Type** dropdown.

**Event Stream Table**

The Event Stream table lists event data for all events triggered by the Sitemap and other event sources from other systems in the Personalization integration. The data in the **Event Stream** table refreshes every 15 seconds and includes this information.

- **Timestamp:** Time or date that the event occurred. Events triggered on the current day have a timestamp of how many minutes/hours ago the event was triggered. Events triggered the day before the current day have a timestamp of `yesterday`. Earlier events have a timestamp of the date the event was triggered.
- **Username or Email:** Username or email address of the user who triggered the event.
- **Action or URL:** Name of the action that triggered the event, or the URL of the page that the user visited that triggered the event.

**Modifying the Event Stream Data View**

You can modify the data displayed in the Event Stream table using these features:

- Sort columns: Click a column heading to sort the table by the data in that field. Click the same column heading again to toggle between ascending and descending data sort.
- View event details: Click an event entry to view its detailed information.

**From Anonymous to Known User**

The example shown in this figure depicts what happens after "Joe Customer" submits their email address. Upon submission, the anonymous user `7ddc1195...` changes to the known user `joe.customer@email.com`. This change happens anytime an anonymous user identifies themselves through an action like email submission or log in. Personalization associates the anonymous ID with the known user and adds the browsing behavior to the [Unified Customer Profile](https://help.salesforce.com/s/articleView?id=sf.mc_pers_unified_customer_profile.htm) of the known user. A known user can have many associated anonymous IDs and more than one known username depending on their browsing habits on the site.

**note:** This image is for example purposes only. In large environments with hundreds or thousands of simultaneous visitors, it’s difficult to visually associate an anonymous user ID with their known username.

![Event Stream Known User Example](https://developer.salesforce.com/media/salesforce-interaction-studio-event-stream-known-user-example.png)

**Individual Event Details**

When you click an individual event in the Event Stream table, the details for that event appears in the Event Detail area next to the Event Stream table.

![Individual Event Details](https://developer.salesforce.com/media/salesforce-interaction-studio-event-stream-event-detail-section.png)

The Event Detail area shows these details for the selected event:

| Field              | Description                                                                                                                                                                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Timestamp**      | Date and time that the event was triggered.                                                                                                                                                                                                                                     |
| **User ID**        | Username, email address, or anonymous user ID of the user who triggered the event.                                                                                                                                                                                              |
| **URL**            | URL returned from `window.location.href` on the page where the event originated.                                                                                                                                                                                                |
| **Client IP**      | IP address of the user client that generated the event.                                                                                                                                                                                                                         |
| **User Agent**     | User Agent (UA) string sent in the HTTP header with browser requests that typically identifies the browser type, browser version, and browser host operating system.                                                                                                            |
| **Beacon Version** | Version of the JavaScript Beacon (Web SDK) that sent the event.                                                                                                                                                                                                                 |
| **pageType**       | The type of page that the user accessed. The preceding figure shows the event of a user accessing the "Men's" category page of a retailer.                                                                                                                                      |
| **contentZones**   | Content Zones defined for the `pageType`. Its value is a combination of `contentZones` defined for the [`PageConfig`](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.md#pageconfig) matched in the Sitemap and `contentZones` defined in the [`GlobalConfig`](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.md#global-config). |
| **channel**        | The engagement channel that generated the event. For Web SDK-generated events, the channel is always `Web`.                                                                                                                                                                     |
| **.scv**           | The Site Configuration Version (SCV) increments every time you save changes to the Sitemap. Personalization uses this value internally to prevent conflicts with events sent from earlier Sitemap versions.                                                                     |

The Event Stream table also includes these additional fields that provide details about specific events, Web SDK and web page performance, and help identify the root cause of Web SDK errors.

| Type               | Field      | Description                                                                                                                                                          |
| ------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Error fields       | **.em**    | Error message describing the issue that occurred. For example, "Response was not OK."                                                                                |
|                    | **.es**    | Section where the error was thrown. For example, "Server Response".                                                                                                  |
|                    | **.eu**    | URL of the resource in which the error was thrown. For example, if the error originated in the Personalization Web SDK, this field shows your JavaScript beacon URL. |
|                    | **.ef**    | Function or method that threw the error. For example, `createCustomError`.                                                                                           |
|                    | **.el**    | Line number in the source code file where the error was thrown.                                                                                                      |
|                    | **.ec**    | Column number in the source code file where the error was thrown.                                                                                                    |
| Performance fields | **.bt**    | Time taken for the Web SDK to load on the web page.                                                                                                                  |
|                    | **.pt**    | Time taken for the Web SDK to parse and process data after it has loaded.                                                                                            |
|                    | **.btdns** | Time taken for the Web SDK to resolve DNS requests.                                                                                                                  |
|                    | **.lt**    | Time taken for the web page to fully load, including all assets such as images, scripts, and stylesheets.                                                            |
|                    | **.dt**    | Time taken for the Document Object Model (DOM) to fully load.                                                                                                        |
|                    | **.tt**    | Time taken for network requests to complete, including any latency or server-side processing time.                                                                   |
|                    | **.ttdns** | Time taken for DNS requests to resolve when sending or tracking events.                                                                                              |

## Event Validation Using Chrome Browser Developer Tools

Sitemap developers can also validate Sitemap events using Google Chrome's built-in developer tools, as described in these sections.

### Viewing Page Load Events

The simplest way to view events that are triggered by page load is to run the `SalesforceInteractions.mcis.getSitemapResult().currentPage` command (or `Evergage.getCurrentPage` in the `Evergage` namespace) from the Chrome **Console** developer panel. However, this command won't show events triggered after page load. To run this command, perform these steps:

1. Exit the Personalization Sitemap Editor.
2. Go to the web page containing the events you want to validate.
3. Open Chrome Developer Tools and go to the **Console** panel.
4. Depending on the namespace used, run either of these commands.

   ```javascript
SalesforceInteractions.mcis.getSitemapResult().currentPage;
```

   ```javascript
Evergage.getCurrentPage();
```

   This image shows an example of the output from the `SalesforceInteractions.getSitemapResult().currentPage` command.

   ![Viewing events triggered by page load using getSitemapResult command](https://developer.salesforce.com/media/sitemap-get-sitemap-result-current-page-command-results.png)

   This image shows an example of the output from the `Evergage.getCurrentPage` command.

   ![Get Current Page Command](https://developer.salesforce.com/media/sitemap-evergage-get-current-page-command-results.png)

### Validating Individual Event Configurations

In the Chrome **Network** developer panel, you can see all events generated on the current page, including those events generated after page load. To view all events generated on the current page:

1. Exit the Personalization Sitemap Editor.
2. Go to the site page containing the events you want to validate.
3. Perform an action on the page that you expect to generate an event.
4. Open Chrome Developer Tools and go to the **Network** panel.
5. Find and select the event. The event contains the name of your dataset followed by a question mark (?) and the word "event".
6. Select the event and then select the **Headers** panel to view the event. Events are sent from the Sitemap to Personalization as JSON GET requests. The events are converted to Base64 and appended to the request URL, as shown in this image.

   ![Event GET Request](https://developer.salesforce.com/media/sitemap-chrome-tools-network-get-request-url-720px.png)

7. Copy the event GET request starting immediately after `event=` to the end, as highlighted in this image.

   ![Copying an Event](https://developer.salesforce.com/media/sitemap-chrome-tools-network-get-request-url-base64.png)

8. Navigate to the Chrome **Console** developer tool. Run the `atob` command to convert the event back to JavaScript objects. You can run the `JSON.parse` command in combination with the `atob` command to return the event JavaScript formatted. To run this command, use this syntax:

   ```javascript
   JSON.parse(atob("<Event text in Base 64>"));
   ```

   This image shows an example of the output from the `atob` command in the `SalesforceInteractions` namespace.

   ![JSON.parse `atob` command](https://developer.salesforce.com/media/sitemap-chrome-tools-console-json-parse-atob-salesforce-interactions.png)

   This image shows an example of the output from the `atob` command in the `Evergage` namespace.

   ![JSON.parse `atob` command](https://developer.salesforce.com/media/sitemap-chrome-tools-console-json-parse-atob.png)

9. Review the event and confirm it contains the expected objects.

## See Also

- [_Salesforce Help_: Event Types](https://help.salesforce.com/s/articleView?id=mktg.mc_pers_event_types.htm)
- [_Salesforce Help_: Event Stream Report](https://help.salesforce.com/s/articleView?id=mktg.mc_pers_report_activity_event_stream.htm)
- [_Salesforce Help_: Unified Customer Profile](https://help.salesforce.com/s/articleView?id=sf.mc_pers_unified_customer_profile.htm)

<!-- document id=0b1fd89839ea6be51fa0ef41952b9da29fb640e4962b560feffa564e47a3881f url=/developer/current/en-us/personalization/personalization/guides/web-integration/sitemap-implementation.md -->

# Sitemap Implementation

The Marketing Cloud Personalization Sitemap system is a configuration-driven integration layer that executes within and is deployed by the Personalization module of the Salesforce Interactions SDK. A Sitemap is developed using the SDK to integrate with a specific site and map key business objects into the Personalization system through event capture. A Sitemap includes page type information, which can additionally include catalog items such as products, articles, content, and categories that support the ability to gauge user interest against the catalog.

**note:** For more information on the Personalization Sitemap, see [Sitemap Overview](https://developer.salesforce.com/docs/marketing/personalization/guide/personalization-sitemap.md). For more information on the Personalization data model, see [Data Model](https://developer.salesforce.com/docs/marketing/personalization/data-modeling.md).

---

**In This Article**

This article details the following topics related to the implementation of a Personalization Sitemap.

- [Sitemap Configuration Type Definitions](#sitemap-configuration-type-definitions)
  - [SiteMapConfig Type Processing](#sitemapconfig-type-processing)
  - [Global Config](#global-config)
  - [Page Types](#page-types)
    - [PageConfig](#pageconfig)
    - [CatalogConfig](#catalogconfig)
    - [CartConfig](#cartconfig)
  - [OrderConfig](#orderconfig)
  - [LineItem](#lineitem)
  - [Interaction](#interaction)
  - [CatalogObjectInteraction](#catalogobjectinteraction)
  - [CartInteraction](#cartinteraction)
  - [OrderInteraction](#orderinteraction)
    - [CatalogConfig Utility Functions](#catalogconfig-utility-functions)
  - [Default Page Config](#default-page-config)
- [Sitemap API](#sitemap-api)
  - [Resolvers](#resolvers)
  - [Utility Functions](#utility-functions)
- [Single Page App Handling](#single-page-app-handling)
- [Sitemap Localization Implementation](#sitemap-localization-implementation)
  - [Example: Setting Locale in the Global Configuration](#example-setting-locale-in-the-global-configuration)
  - [Catalog Configurations in Different Locales](#catalog-configurations-in-different-locales)
  - [Order Configuration in Different Locales](#order-configuration-in-different-locales)

---

**Example Sitemaps**

The following is a list of example Sitemaps we've created for different types of business websites that depict how you could approach designing a Sitemap for your Personalization implementation. While the JavaScript and HTML code in these example Sitemaps are only for reference purposes, they can give you a head start in developing the Sitemap for your implementation.

- [Financial services](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps/financial-services.md)
- [ecommerce](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps/ecommerce.md)
- [B2B](https://developer.salesforce.com/docs/marketing/personalization/guide/example-sitemaps/b2b.md)

---

## Sitemap Configuration Type Definitions

A `SiteMapConfig` consists of the following three, separate configurations.

- `global`: The `global` configuration contains objects to be monitored by Personalization on all page type configuration objects, and the default page configuration (if defined) of your site.
- `pageTypes`: The `pageTypes` configuration contains objects used to detect/match each different page type to be monitored on your site.
- `pageTypeDefault`: If defined, the objects configured in `pageTypeDefault` are matched when all `PageConfig` objects in the `pageTypes` array resolve to `false`. Do remember that the `pageTypeDefault` matches this way only when the sitemap contains _at least one_ validly constructed `PageConfig` object. When using the `SalesforceInteractions` namespace, an interaction must be provided for `pageTypeDefault`.

The following sections describe how the preceding Sitemap configuration types are processed and provide additional information about each configuration type.

### SiteMapConfig Type Processing

When the configuration for either a `PageConfig` object inside the `pageTypes` array or the `pageTypeDefault` matches a page on the site, the matched configuration merges with anything defined within `GlobalConfig`. Individual attributes are merged in the following manner.

- `locale` : the matched `PageConfig` or `DefaultPageConfig` takes precedence
- `contentZones`: concatenate
- `listeners`: concatenate
- `onActionEvent`: the function for the matched `PageConfig` or `DefaultPageConfig` executes first, followed by the function for the `GlobalConfig`

The result of this merge is then evaluated as expected.

```typescript
{
  global: GlobalConfig,
  pageTypeDefault: DefaultPageConfig,
  pageTypes: PageConfig[]
}
```

---

### Global Config

`GlobalConfig` defines the additional data to be tracked if a `PageConfig` or `DefaultPageConfig` matches a specific page.

```typescript
{
  locale?: string | () => string,
  contentZones?: ContentZone[],
  listeners?: Listener[],
  onActionEvent?: (event: ActionEvent) => ActionEvent
}
```

---

### Page Types

Page type configurations use a `pageTypes` array to declare how to detect that a given URL or loaded page is one of the known page types. Each page type configuration must contain properties for `name`, `action`, and `isMatch`, which declares the function used to detect that page type. Additionally, individual page type configurations can declare [Content Zones](https://developer.salesforce.com/docs/marketing/personalization/guide/content-zones.md) representing key parts of a page designed for personalization adjustments. The configurations can also declare other event listeners for a given page type, such as an "add to cart" listener. Page types can map to more than a single page; for example, while the **Home** page is an example of a page type with only a single instance of a page, the product display page (PDP) type would have separate URLs for every product on the site, but only a single page type.

For more information on page types, refer to the [Page Types](https://developer.salesforce.com/docs/marketing/personalization/guide/page-types.md) documentation.

#### PageConfig

`PageConfig` defines the data to be tracked for a specific page. The `PageConfig` object accepts the following fields.

```javascript
{
  name: string, // required
  isMatch: () => boolean | () => Promise<boolean>, // required
  locale?: string | () => string,
  interaction?: Interaction,
  contentZones?: ContentZone[],
  listeners?: Listener[],
  onActionEvent?: (event: ActionEvent) => ActionEvent
}
```

```javascript
{
    name: string, // required
    isMatch: () => boolean | () => Promise<boolean>, // required
    locale?: string | () => string,
    action?: string,
    itemAction?: string,
    catalog?: CatalogConfig,
    cart?: CartConfig,
    order?: OrderConfig,
    contentZones?: ContentZone[],
    listeners?: Listener[],
    onActionEvent?: (event: ActionEvent) => ActionEvent
}
```

The following table describes the fields that a `PageConfig` accepts.

| Field           | Expected Value Type                                                                 | Required? | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Namespace                |
| --------------- | ----------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `name`          | String                                                                              | **Yes**   | The page type that gets sent in the event when this configuration is evaluated. Example: Homepage, Product Detail                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Both                     |
| `isMatch`       | `() => boolean \| Promise<boolean>`                                                 | **Yes**   | The function provided here is evaluated when the sitemap is deciding which `PageConfig` to evaluate. The sitemap only evaluates the first `PageConfig` whose `isMatch` resolves to `true`. If no `isMatch` resolves to `true`, then the `pageTypeDefault` configuration runs.                                                                                                                                                                                                                                                                                                                                                                       | Both                     |
| `locale`        | String                                                                              | No        | The locale of the page (for example, `en_US`). Use `locale` only if you have catalog localization enabled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Both                     |
| `action`        | String                                                                              | No        | The name of the action dispatched in the event when this configuration is evaluated. **Important**: Capture actions only if they’re necessary for personalization and targeting. Actions must have names that can be reused across users and sessions. If you dynamically populate action names, ensure that these names stay consistent across sessions for any user performing the action. Dynamic user information in action names can cause issues and should be avoided whenever possible. For more information and best practices on using actions, see [Best Practices For Using Actions](https://developer.salesforce.com/docs/marketing/personalization/guide/item-actions.md#best-practices-for-using-actions). | `Evergage`               |
| `itemAction`    | String                                                                              | No        | The name of the itemAction dispatched in the event when this configuration is evaluated.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `Evergage`               |
| `interaction`   | `Interaction`, `CatalogObjectInteraction`, `CartInteraction`, or `OrderInteraction` | No        | An object describing the interaction on the page. For more information, refer to the [Interaction](#interaction) section of this article. For more information and best practices on using actions, see [Best Practices For Using Interactions](https://developer.salesforce.com/docs/marketing/personalization/guide/interaction-definitions.md#best-practices-for-using-interactions).                                                                                                                                                                                                                                                                                                                                  | `SalesforceInteractions` |
| `catalog`       | `CatalogConfig`                                                                     | No        | The catalog data to be captured. For more information, refer to the [CatalogConfig](#catalogconfig) section of this article.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Evergage`               |
| `cart`          | `CartConfig`                                                                        | No        | The cart data to be captured. For more information, refer to the [CartConfig](#cartconfig) section of this article.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Evergage`               |
| `order`         | `OrderConfig`                                                                       | No        | The order data to be captured. For more information, refer to the [OrderConfig](#orderconfig) section of this article.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `Evergage`               |
| `contentZones`  | `ContentZone[]`                                                                     | No        | The content zones defined in the sitemap determine where Personalization campaigns are rendered throughout a website. Personalization templates reference these content zones for targeting within campaigns. For more information on content zones, refer to the [Content Zones](https://developer.salesforce.com/docs/marketing/personalization/guide/content-zones.md) documentation.                                                                                                                                                                                                                                                                                                                                  | Both                     |
| `listeners`     | `Listener[]`                                                                        | No        | The event listeners to be bound when this configuration is evaluated. For more information, refer to the [Listeners](#listeners) section of this article.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Both                     |
| `onActionEvent` | `(event: ActionEvent) => ActionEvent`                                               | No        | The `onActionEvent` function modifies the outgoing `ActionEvent`. This function runs whenever the sitemap builds an `ActionEvent` before sending it to Personalization. The sitemap builds the `ActionEvent` as a result of calling the `sendEvent` function or building a `PageConfig` array. If the GlobalConfig and a matched PageConfig array contain the `onActionEvent` function, then both functions are executed. The function in `PageConfig` is executed before executing the function in the `GlobalConfig` array.                                                                                                                       | Both                     |

---

#### Default Page Config

`DefaultPageConfig` defines the default page configuration to use if no other page types are matched. When using `DefaultPageConfig` with the `SalesforceInteractions` namespace, an interaction must be provided.

```javascript
{
  name: string,
  interaction: Interaction
}
```

```javascript
{
  name: string;
}
```

#### CatalogConfig

`CatalogConfig` defines the catalog data to be captured and accepts the following fields. A `catalog` object accepts the following fields.

**important:** Only available in the `SalesforceInteractions` namespace.

```javascript
catalog: {
    <ItemType>: {
        _id: string | () => string | () => Promise<string | () => string> // required
        categories?: string[] | () => string[] | () => Promise<string[] | () => string[]>
        <attributes>?: value | () => value,
        relatedCatalogObjects?: { // In case you're using 'dimensions' instead of 'relatedCatalogObjects', you can continue to do so as they both function the same way.
            <relatedCatalogObject>?: string[] | () => string[] | () => Promise<string[] | () => string[]>
        },
        attributes?: {
            <attribute>?: value | () => value
        }
    }
}
```

The `ItemType` in a `CatalogConfig` is defined in the **Catalog and Profile Objects** section of the Personalization UI. An `ItemType` can refer to items such as products, content, blogs, or any other catalog object, whether built in or user-defined. The following table describes the fields that an `ItemType` array accepts.

| Field                  | Expected Value Type                                                       | Required? | Description                                                                                                                                                                                                                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_id`                  | `string \| () => string \| () => Promise<string \| () => string>`         | **Yes**   | The ID of the catalog item. This field is required for an item to be tracked. **Important:** When capturing catalog items IDs, avoid capturing line break characters (`\n`). This character isn't supported in IDs of catalog items, interactions, and actions. Including line breaks in the IDs can cause issues in the UI. |
| `categories`           | `string[] \| () => string[] \| () => Promise<string[] \| () => string[]>` | No        | The categories the catalog item belongs to.                                                                                                                                                                                                                                                                                  |
| `<attributes>`         | `value \| () => value`                                                    | No        | Use this field to define standard, built-in item attributes. Examples of attributes include `_id`, `name`, `price`, and so on.                                                                                                                                                                                               |
| `relatedCatalogObject` | `string[] \| () => string[] \| () => Promise<string[] \| () => string[]>` | No        | Catalog objects can be assigned to other catalog objects to describe them in more detail. When so assigned, it is considered a related catalog object.                                                                                                                                                                       |
| `attributes`           | `value \| () => value`                                                    | No        | Custom attributes on an item, as defined in the **Catalog Setup** section of the Personalization UI.                                                                                                                                                                                                                         |

For more details on catalog items and item attributes, see [Create a Custom Catalog Object](https://help.salesforce.com/s/articleView?id=sf.mc_pers_catalog_object_custom.htm).

#### CartConfig

`CartConfig` defines the cart data to be captured. The `cart` object accepts the following fields.

**important:** Only available in the `SalesforceInteractions` namespace.

```javascript
cart: {
    complete: {
        <ItemType>: LineItem[]
    }
}
```

When including a `CartConfig` in a `pageType`, ensure that it follows the following structure.

**important:** Only available in the `SalesforceInteractions` namespace.

```javascript
cart: {
    complete: {
        <ItemType>: {
            lineItem: {
                _id: string[],
                price: double[],
                quantity: integer[]
            }
        }
    }
}
```

Additionally, a user's cart can be emptied by sending an event with an empty array of `LineItems`.

```javascript
{
  cart: {
    complete: {
      Product: [];
    }
  }
}
```

### OrderConfig

`OrderConfig` defines the order data to be captured. An `order` object accepts the following fields.

**important:** Only available in the `Evergage` namespace.

```javascript
order: {
    <ItemType>: {
        orderId: string | () => string | Promise<string | () => string>,
        totalValue?: double | () => double | Promise<double | () => double>,
        currency?: string | () => string | Promise<string | () => string>,
        lineItems: LineItem[]
    }
}
```

### LineItem

`LineItem` represents a single item in a cart/transaction. A `LineItem` object accepts the following fields.

**important:** Only available in the `Evergage` namespace.

```javascript
{
    _id: string | () => string | Promise<string | () => string>
    price: double | () => double | Promise<value | ()=> double>
    quantity: integer | () => integer | Promise<value | ()=> integer>
}
```

### Interaction

`Interaction` represents the interaction the user is taking on the page. An `Interaction` object accepts the following fields.

**important:** Only available in the `SalesforceInteractions` namespace.

```javascript
{
  name: string; // required
}
```

### CatalogObjectInteraction

`CatalogObjectInteraction` is an extension of `Interaction` that accepts a `catalogObject`. A `CatalogObjectInteraction` object accepts the following fields.

**important:** Only available in the `SalesforceInteractions` namespace.

```javascript
{
    name: CatalogObjectInteractionName,
    catalogObject: {
        type: string,
        id: string,
        attributes?: { [key: string]: any },
        relatedCatalogObjects?: { [catalogObjectType: string]: string[] }
    }
}
```

For all `CatalogObjectInteractions`, refer to the [CatalogObjectInteraction](https://developer.salesforce.com/docs/marketing/personalization/guide/interaction-definitions.md#catalogobjectinteraction) documentation.

### CartInteraction

`CartInteraction` is an extension of `Interaction` that accepts information about a cart. A `CartInteraction` object accepts the following fields.

**important:** Only available in the `SalesforceInteractions` namespace.

```javascript
{
    name: CartInteractionName,
    lineItem?: LineItem,
    lineItems?: LineItem[]
}
```

In a `CartInteraction`, `LineItem` accepts the following fields.

```javascript
{
    catalogObjectType: string,
    catalogObjectId: string,
    quantity: number,
    price?: number,
    currency?: string,
    attributes?: { [key: string]: any }
}
```

For all `CartInteractions`, refer to the [CartInteraction](https://developer.salesforce.com/docs/marketing/personalization/guide/interaction-definitions.md#cartinteraction) documentation.

### OrderInteraction

`OrderInteraction` is an extension of `Interaction` that accepts information about an order. An `OrderInteraction` object accepts the following fields.

**important:** Only available in the `SalesforceInteractions` namespace.

```javascript
{
    name: OrderInteractionName,
    order: {
        id: string;
        lineItems?: LineItem[];
        totalValue?: number;
        currency?: string;
        attributes?: { [key: string]: any };
    }
}
```

In an `OrderInteraction`, `LineItem` accepts the following fields.

```javascript
{
    catalogObjectType: string,
    catalogObjectId: string,
    quantity: number,
    price?: number,
    currency?: string,
    attributes?: { [key: string]: any }
}
```

For all `OrderInteractions`, refer to the [OrderInteraction](https://developer.salesforce.com/docs/marketing/personalization/guide/interaction-definitions.md#orderinteraction) documentation.

#### CatalogConfig Utility Functions

The Personalization module of the Salesforce Interactions SDK includes the following utility function that is especially helpful for building LineItems.

```javascript
SalesforceInteractions.mcis.buildLineItemFromPageState(quantitySelector) => LineItem
```

```javascript
Evergage.util.buildLineItemFromPageState(quantitySelector) => LineItem
```

The preceding utility function returns a `LineItem` constructed from the data already captured on the page using the given `quantitySelector` to determine the number of items in the line item.

---

### Default Page Config

The `DefaultPageConfig` defines what data is tracked _only if_ all other `PageConfig`s resolve to `false`.

The `DefaultPageConfig` accepts the following fields.

```typescript
{
    name: string, // required
    locale?: string | () => string,
    contentZones?: ContentZone[],
    listeners?: Listener[],
    onActionEvent?: (event: ActionEvent) => ActionEvent
}
```

**note:** The `DefaultPageConfig` works only when the sitemap contains _at least one_ validly constructed `PageConfig` object.

---

## Sitemap API

The Sitemap API is scoped on the `window` under `Evergage`.

### initSitemap

Initialize the sitemap process using the provided configuration. Events are not sent to Personalization unless this function is called.

```javascript
SalesforceInteractions.initSitemap(siteMapConfig: *SiteMapConfig*) => void
```

```javascript
Evergage.initSitemap(siteMapConfig: *SiteMapConfig*) => void
```

### cashDom

A small library for modern browsers that provides jQuery-style syntax to wrap modern Vanilla JS features and select elements from the DOM. For more information on `Cash`, refer to the [Cash documentation](https://kenwheeler.github.io/cash/#docs).

```javascript
SalesforceInteractions.cashDom(selector: *String*, context) => Cash
```

```javascript
Evergage.cashDom(selector: *String*, context) => Cash
```

### sendEvent

Send a custom event to Personalization.

```javascript
SalesforceInteractions.sendEvent(event: *ActionEvent*)
```

```javascript
Evergage.sendEvent(event: *ActionEvent*)
```

### getSitemapResult

Get the current page state, including values in the configuration that have already been resolved.

```javascript
SalesforceInteractions.mcis.getSitemapResult();
```

```javascript
Evergage.getSitemapResult()
```

---

### Listeners

Create a listener.

```javascript
SalesforceInteractions.listener(bind: keyof WindowEventMap, selector: string, callback: Function): Listener;
```

```javascript
Evergage.listener(bind: keyof WindowEventMap, selector: string, callback: Function): Listener;
```

You can use a listener to "listen" for user actions on a page, capture information from that action, and initiate a function or action based on the captured information. Listeners are structurally similar to jQuery's event listeners.

The following are examples of simple listeners that bind a click to the banner of a website and dispatch an event to Personalization.

```javascript
SalesforceInteractions.listener("click", ".header-banner", () => {
  SalesforceInteractions.sendEvent({ interaction: { name: "Banner Click" } });
});
```

```javascript
Evergage.listener("click", ".header-banner", () => {
  Evergage.sendEvent({ action: "Banner Click" });
});
```

The following are namespace-specific examples of listeners that capture email addresses using a custom callback function.

```javascript
SalesforceInteractions.listener("submit", "form#subscribe", (e) => {
  const userEmail = SalesforceInteractions.cashDom(e.target).find("#email").val();
  if (typeof userEmail === "string" && /^.+@.+\..+$/.test(userEmail)) {
    SalesforceInteractions.sendEvent({
      interaction: {
        name: "Email Capture",
      },
      user: {
        identities: { emailAddress: userEmail },
      },
    });
  }
});
```

```javascript
Evergage.listener("submit", "form#subscribe", (e) => {
  const userEmail = Evergage.cashDom(e.target).find("#email").val();
  if (typeof userEmail === "string" && /^.+@.+\..+$/.test(userEmail)) {
    Evergage.sendEvent({
      action: "Email Capture",
      user: {
        attributes: { emailAddress: userEmail },
      },
    });
  }
});
```

---

### Resolvers

Resolvers return functions so that they can be invoked _after_ a page has been matched. When used in a `PageConfig`, the returned functions do not need to be invoked to get the final value - the underlying sitemap code handles that logic.

```javascript
SalesforceInteractions.resolvers.<resolver>
```

```javascript
Evergage.resolvers.<resolver>
```

`transform` functions are callbacks designed to evaluate or modify the resolved value.

```typescript
fromSelector(selector: string, transform?: (string) => string) => () => string
```

```javascript
SalesforceInteractions.cashDom(selector).text();
```

```javascript
Evergage.cashDom(selector).text();
```

Returns the text of the first instance of the selector in the DOM.

```typescript
fromSelectorMultiple(selector: string, transform?: (string[]) => string[]) => () => string[]
```

```javascript
[SalesforceInteractions.cashDom(selector).eq(0).text(), SalesforceInteractions.cashDom(selector).eq(1).text(), ...]
```

```javascript
[Evergage.cashDom(selector).eq(0).text(), Evergage.cashDom(selector).eq(1).text(), ...]
```

Returns the text of all instances of the selector in the DOM in an array.

```typescript
fromSelectorAttribute(selector: string, attribute: string, transform?: (string) => string) => () => string
```

```javascript
SalesforceInteractions.cashDom(selector).attr(attribute);
```

```javascript
Evergage.cashDom(selector).attr(attribute);
```

Returns the attribute of the first instance of the selector in the DOM.

```typescript
fromSelectorAttributeMultiple(selector: string, attribute: string, transform?: (string[]) => string[]) => () => string[]
```

```javascript
[SalesforceInteractions.cashDom(selector).eq(0).attr(attribute), SalesforceInteractions.cashDom(selector).eq(1).attr(attribute), ...]
```

```javascript
[Evergage.cashDom(selector).eq(0).attr(attribute), Evergage.cashDom(selector).eq(1).attr(attribute), ...]
```

Returns the attributes of all instances of the selector in the DOM as an array.

```typescript
fromMeta(metaName: string, transform?: (string) => string) => () => string
```

```javascript
SalesforceInteractions.cashDom("meta[name='" + metaName + "']")
  .first()
  .attr("content");
```

```javascript
Evergage.cashDom("meta[name='" + metaName + "']")
  .first()
  .attr("content");
```

Returns the content of the first meta tag with the given meta tag name.

```typescript
fromItemProp(itemProp: string, transform?: (string) => string) => () => string
```

```javascript
SalesforceInteractions.cashDom("[itemprop='" + itemProp + "']")
  .first()
  .attr("content");
```

```javascript
Evergage.cashDom("[itemprop='" + itemProp + "']")
  .first()
  .attr("content");
```

Returns the content of the first `itemProp` with the given `itemProp`.

```typescript
fromWindow(windowVar: string, transform?: (string) => string) => () => string
```

Returns the value from a nested object. Returns `null` if the nested object, or some object in the path, does not exist.

```typescript
fromJsonLd(path: string, transform?: any) => () => any
```

```javascript
SalesforceInteractions.cashDom("script[type='application/ld+json']").first().text();
```

```javascript
Evergage.cashDom("script[type='application/ld+json']").first().text();
```

If the path is `null`, the first JSON-LD script is returned after being parsed into a JavaScript object. If a path is provided, then the value of the path from the parsed JavaScript object is returned.

```typescript
buildCategoryId(selector: string, startFrom?: integer, ignoreLast?: boolean, transform?: (string) => string) => () => string
```

```javascript
SalesforceInteractions.cashDom(selector).eq(startFrom).text()|SalesforceInteractions.cashDom(selector).eq(startFrom+1).text()|...
```

```javascript
Evergage.cashDom(selector).eq(startFrom).text()|Evergage.cashDom(selector).eq(startFrom+1).text()|...
```

Returns a pipe-delimited string using the text of all instances of the selector.

```typescript
buildCategoryIdAttribute(selector: string, attribute: string, startFrom?: integer, ignoreLast?: boolean, transform?: (string) =>  string) => () => string
```

```javascript
SalesforceInteractions.cashDom(selector).eq(startFrom).attr(attribute)|SalesforceInteractions.cashDom(selector).eq(startFrom+1).attr(attribute)|...
```

```javascript
Evergage.cashDom(selector).eq(startFrom).attr(attribute)|Evergage.cashDom(selector).eq(startFrom+1).attr(attribute)|...
```

Returns a pipe-delimited string using the given attribute of all instances of the selector.

```typescript
fromCanonical(transform?: (string) => string) => () => string
```

Returns a canonical URL, if one exists on the page.

```typescript
fromHref(transform?: (string) => string) => () => string
```

Returns the value stored in `window.location.href`

---

### Utility Functions

The Personalization module of the Salesforce Interactions SDK provides several utility functions that you can use to help parse data.

```javascript
SalesforceInteractions.mcis.<util>
```

```javascript
Evergage.util.<util>
```

The following table describes these utility functions in detail.

| Utility Function                                                                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Namespace  |
| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `buildLineItemFromPageState(quantitySelector: string) => LineItem`                                                     | Returns a `LineItem` constructed from the data already captured on the page, using the given `quantitySelector` to determine how many of the items are in the `lineItem`.                                                                                                                                                                                                                                                                                                                | Both       |
| `extractFirstGroup(regex: RegExp, str: string) => string`                                                              | Returns a string of the first group extracted from the provided regex.                                                                                                                                                                                                                                                                                                                                                                                                                   | Both       |
| `getFloatValue(text: string) => number`                                                                                | Returns a floating point number parsed from the provided string.                                                                                                                                                                                                                                                                                                                                                                                                                         | `Evergage` |
| `getIntegerValue(text: string) => number`                                                                              | Returns an integer number parsed from the provided string.                                                                                                                                                                                                                                                                                                                                                                                                                               | `Evergage` |
| `getLastPathComponent(url: string) => string`                                                                          | Returns the last path component for the provided URL. For example, `SalesforceInteractions.util.getLastPathComponent("https://example.example/myExamplePath.html")` returns `myExamplePath.html`.                                                                                                                                                                                                                                                                                        | `Evergage` |
| `getLastPathComponentWithoutExtension(url: string) => string`                                                          | Returns the last path component without an extension for the provided URL. For example, `SalesforceInteractions.util.getLastPathComponent("https://example.example/myExamplePath.html")` returns `myExamplePath`.                                                                                                                                                                                                                                                                        | Both       |
| `getParameterByName(name: string, url?: string) => string`                                                             | Returns the value of the provided parameter name from the provided URL. If no URL is provided, the current `location.search` of the page is used.                                                                                                                                                                                                                                                                                                                                        | Both       |
| `getPathname(url: string) => string`                                                                                   | Returns the `Pathname` of the provided URL.                                                                                                                                                                                                                                                                                                                                                                                                                                              | `Evergage` |
| `getUtagFirstForField(fieldName: string) => any`                                                                       | Returns the first value for the provided field in a `window.utag_data` object.                                                                                                                                                                                                                                                                                                                                                                                                           | `Evergage` |
| `getValueFromNestedObject(path: string, obj?: object) => any`                                                          | Returns the value from a nested object. If an object is not provided, `window` is used. Returns `null` if the nested object, or some object in the path, does not exist.                                                                                                                                                                                                                                                                                                                 | Both       |
| `qualifyUrl(unqualified: string) => string`                                                                            | Returns a qualified URL href from an unqualified relative URL path. If unqualified is null or unprovided, returns null.                                                                                                                                                                                                                                                                                                                                                                  | `Evergage` |
| `removeQueryString(url: string) => string`                                                                             | Returns a URL without query strings from the provided URL.                                                                                                                                                                                                                                                                                                                                                                                                                               | `Evergage` |
| `resolveWhenTrue.bind(trueFunc: () => any, bindId?: string, timeout?: number, checkInterval?: number) => Promise<any>` | Returns a Promise that resolves when the provided `trueFunc` evaluates to `true`.DONE If `timeout` is not provided, a 2000-ms default timeout is used. If `checkInterval` is not provided, a 100-ms default interval is used to check the trueFunc. If the timeout is reached, the check is unbound. An `unbind` function is provided under `resolveWhenTrue.getBindings()`. If a `bindId` is provided, the `unbind` function is mapped to that key, otherwise a new random key is used. | Both       |
| `resolveWhenTrue.unbind(bindId: string) => void`                                                                       | When given a `bindId` unbinds that bound `resolveWhenTrue` function.                                                                                                                                                                                                                                                                                                                                                                                                                     | Both       |
| `resolveWhenTrue.getBindings() => [key: string]: unbindFunction: ()`                                                   | Returns a map of currently bound `resolveWhenTrue` functions.                                                                                                                                                                                                                                                                                                                                                                                                                            | Both       |
| `resolveWhenTrue.clearBindings() => void`                                                                              | Clears all currently bound `resolveWhenTrue` functions.                                                                                                                                                                                                                                                                                                                                                                                                                                  | Both       |

---

## Single Page App Handling

Depending on the SDK namespace you're using, use either of the following code snippets to reinitialize the beacon and the Sitemap when using Personalization on a single-page application (SPA).

```javascript
SalesforceInteractions.reinit();
```

```javascript
Evergage.reinit();
```

Executing the preceding code results in the following.

1. Depending on the SDK namespace you're using, dispatch a `SalesforceInteractions.CustomEvents.OnInit` or an `Evergage.CustomEvents.OnInit` event.
2. Reinitialize the beacon with the same settings as the initial page load (for example, `cookieDomain`).
3. Rerun the sitemap using the same configuration as the initial page load.
4. Send activity timing for the previous page.
5. Start activity timers for the current page.

Ensure that you wrap the reinitialization function in logic to determine when to reinitialize the beacon and sitemap. The following is a sample sitemap code that includes logic to reinitialize the beacon and sitemap when the URL changes without a full page load.

**note:** The following sitemap code examples are for illustrative purposes only. We recommend considering other ways of using the reinitialization function that better suits your specific use case, and the way your site functions.

```javascript
SalesforceInteractions.init().then(() => {

    const config = {
        global: {},
        pageTypes: [
            {
                name: "home",
                interaction: {
                    name: "Homepage"
                },
                isMatch: () => /home/.test(window.location.href);
            }
        ]
    };

    /*
        Check for URL change every 2 seconds. If URL has changed, reinitialize beacon and sitemap.
    */
    const handleSPAPageChange = () => {
        let url = window.location.href;
        const urlChangeInterval = setInterval(() => {
            if (url !== window.location.href) {
                url = window.location.href;
                SalesforceInteractions.reinit();
            }
        }, 2000);
    }

    handleSPAPageChange();

    SalesforceInteractions.initSitemap(config);
})
```

```javascript
Evergage.init().then(() => {

    const config = {
        global: {},
        pageTypes: [
            {
                name: "home",
                isMatch: () => /home/.test(window.location.href);
            }
        ]
    };

    /*
        Check for URL change every 2 seconds. If URL has changed, reinitialize beacon and sitemap.
    */
    const handleSPAPageChange = () => {
        let url = window.location.href;
        const urlChangeInterval = setInterval(() => {
            if (url !== window.location.href) {
                url = window.location.href;
                Evergage.reinit();
            }
        }, 2000);
    }

    handleSPAPageChange();

    Evergage.initSitemap(config);
})
```

---

## Sitemap Localization Implementation

The localization setting enables a single dataset to cater to a site with multiple languages and locales while leveraging the same catalog and sitemap across those languages and locales. The use of localization requires sending the locale attribute in an event.

**important:** To use catalog localizations, you must check the **Enable Localization of Catalog Metadata Based on Page Locale** setting in a catalog's settings via the Personalization UI by navigating to **Settings** > **Catalog and Profile Objects**.

Locales must be set in a specific format of an [ISO 639 alpha-2](https://en.wikipedia.org/wiki/ISO_639-1) language code, followed by an underscore, followed by an [ISO 3166 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. The following list contains examples of valid locales.

- `en_US`
- `en_AU`
- `en_CA`
- `zh_CN`
- `en_GB`
- `pt_PT`
- `en_HK`
- `zh_HK`

### Example: Setting Locale in the Global Configuration

The following is an example of a View Item event that depicts how to send an event with a locale. You can set the locale on the `global`, `pageTypeDefault`, and individual `pageTypes` configurations in the `SiteMapConfig`. You can set the locale manually in events tracked through `sendEvent` functions.

```javascript
SalesforceInteractions.init().then(() => {
  const buildLocale = () => {
    let locale = SalesforceInteractions.CashDom("meta[type='locale']").attr("content");
    return locale;
  };

  const config = {
    global: {
      locale: buildLocale(),
    },
    pageTypeDefault: {
      name: "default",
    },
    pageTypes: [
      {
        name: "home",
        interaction: {
          name: "Homepage",
        },
        isMatch: () => {
          return window.location.pathname === "/";
        },
      },
    ],
  };

  SalesforceInteractions.initSitemap(config);
});
```

```javascript
Evergage.init().then(() => {
  const buildLocale = () => {
    let locale = Evergage.CashDom("meta[type='locale']").attr("content");
    return locale;
  };

  const config = {
    global: {
      locale: buildLocale(),
    },
    pageTypeDefault: {
      name: "default",
    },
    pageTypes: [
      {
        name: "home",
        action: "Homepage",
        isMatch: () => {
          return window.location.pathname === "/";
        },
      },
    ],
  };

  Evergage.initSitemap(config);
});
```

### Catalog Configurations in Different Locales

When building catalog configurations in a sitemap, different locales can all use the same configuration. Localized attributes are all on the same item in Personalization. Therefore, when selecting which `_id` to use for a Catalog Item, or a Catalog Item's related catalog objects, ensure that you select an `_id` that does not change depending on the page's locale. Failing to do so creates extra Catalog Items and related catalog objects in the catalog and split attribution for users between different site locales. All item types can be localized.

For products, ensure that `currency`, if available, is captured in the catalog along with `price`. The `currency` attribute takes an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-character string currency code as its value and can change based on locale.

The following are example `catalog` objects with a `currency` attribute specified.

```javascript
catalogObject: {
    type: "Product",
    id: getProductId(),
    attributes: {
        name: getProductName(),
        price: getProductPrice(),
        currency: "AUD"
    }
}
```

```javascript
catalog: {
    Product: {
        _id: getProductId(),
        name: getProductName(),
        price: getProductPrice(),
        currency: "AUD"
    }
}
```

The following list contains examples of valid currencies.

- `USD`
- `AUD`
- `THB`
- `EUR`
- `BRL`
- `DKK`

### Order Configuration in Different Locales

When creating an order configuration on a dataset that includes locales, an additional field in the order configuration is required to calculate total revenue correctly. The `currency` attribute takes an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-character string currency code as its value. If no currency is provided, the default currency on the dataset is applied as the currency for items in the `order` object.

The following are example `order` objects with a `currency` attribute specified.

```javascript
{
  ...
  order: {
    id: "testOrder123",
    totalValue: 120.25,
    currency: "AUD",
    lineItems: LineItem[]
  }
  ...
}
```

```javascript
{
    ...
      order: {
          Product: {
              orderId: "testOrder123",
              totalValue: 120.25,
              currency: "AUD",
              lineItems: {
                  _id: string[],
                  price: double[],
                  quantity: integer[]
                }
            }
        }
    ...
}
```

## See Also

- [_Salesforce Help_: Create a Custom Catalog Object](https://help.salesforce.com/s/articleView?id=sf.mc_pers_catalog_object_custom.htm)
- [_External Link_: Cash Documentation](https://github.com/fabiospampinato/cash#documentation)

<!-- document id=4b3fae1be9bd19a1b474837e8664bf8243d5af29dc52358be4d3172de2c90bbc url=/developer/current/en-us/personalization/personalization/guides/custom-interface-template-configuration/static-values.md -->

# Static Values

The configuration system can also output static text meant to help a user operate the interface such as, documentation, explanations, or even a dynamically calculated phrase.

```typescript
readonly staticText = "This text will appear in the output"
```

Using fat arrow functions, you can also make the output text dynamic.

```typescript
name : string;
readonly output = () => `Hello ${this.name}!`;
```

<!-- document id=b3619919f17edb4d5fced680216dab35a474a3b48f40ad4d0aab2de530cae273 url=/developer/current/en-us/personalization/personalization/guides/custom-interface-template-configuration/properties/string.md -->

# String Property

## Simple Text Input

A basic text input.

```typescript
simpleTextProperty: string = "This is the default text";
```

![Simple Text Property](https://developer.salesforce.com/media/interface-template-configuration/SimpleText.png)

---

## Enumerated Values

A static list of options can be provided using the TypeScript _String Literal_ type system. Doing so provides a dropdown menu with the options.

```typescript
simpleOption: "First Option" | "Second Option" | "Third Option";
```

Alternatively, a static list of options can be provided using an `@options` decorator.

```typescript
@options(["First Option", "Second Option", "Third Option"])
simpleOption: string;
```

![Simple Option](https://developer.salesforce.com/media/interface-template-configuration/SimpleOption.png)

See [Select Property](https://developer.salesforce.com/docs/marketing/personalization/guide/select.md) for more complex dropdown examples.

## Multi-Valued Properties

Simple fields can be made multi-valued capable by simply declaring their field types to be arrays.

```typescript
@options(["First Option", "Second Option", "Third Option", "Fourth Option"])
simpleOption: string[];
```

![Multi-valued Property](https://developer.salesforce.com/media/interface-template-configuration/multivalued-simple-property.png)

## Literal Types

For strong typing in your code, you can also use string literal types, including in array based multi-valued properties.

These values provide the available options to a dropdown just as the `@options` decorator.

```typescript
unionType: ("Alpha" | "Beta" | "Gamma" | "Delta" )[];
```

![Literal Type Property](https://developer.salesforce.com/media/interface-template-configuration/union-types.png)

---

## Rich Text Input

Provides a rich text editor that outputs its value as a string of HTML.

```typescript
@richText(true)
richTextProperty : string = "Example <span style='font-weight:bold;'>Rich Text</span> Content";
```

![Rich Text](https://developer.salesforce.com/media/interface-template-configuration/RichText.png)

---

## See Also

- [Select Property](https://developer.salesforce.com/docs/marketing/personalization/guide/select.md)
- [Static Values](https://developer.salesforce.com/docs/marketing/personalization/static-values.md)
- [Arrays](https://developer.salesforce.com/docs/marketing/personalization/arrays.md)

<!-- document id=a9a0f2ce5b5b026823c9c78b312b15ed3c8759657f40096d1ff8310a4ef3ec84 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/templates/template-client-javascript.md -->

# Template Client JavaScript

When a campaign is returned to the browser, the client-side JavaScript code written within the template editor's **Clientside Code** tab is run. Here, a template developer can write any JavaScript code compatible with the target browsers of their website. The context is passed from the server to the client-side code, determining what to do with the data.

This article outlines the following JavaScript functions used within the template's **Clientside Code** tab.

- `apply`
- `reset`
- `control`

## Template Apply, Reset, and Control Functions

The JavaScript you write in a template's **Clientside Code** tab executes in the browser when a campaign using that template returns from the Marketing Cloud Personalization server. The template's code must register two functions: `apply` and `reset`. The template's code can also register a `control` function for handling the control group of a campaign.

When a campaign is returned to the web browser, the user is in either a "Test" group or the "Control" group. If the user is in a "Test" group, the template executes the `apply` function. Likewise, if the user is in the "Control" group, the template executes the `control` function.

The following code sample displays the boilerplate code for a new template.

**note:** The `registerTemplate` function is not defined in any public scope.

```javascript
(function () {
  function apply(context, template) {}

  function reset(context, template) {}

  function control(context) {}

  registerTemplate({
    apply: apply,
    reset: reset,
    control: control,
  });
})();
```

### Apply

A template calls the `apply` function when provided with a `context` to handle or render visible content on the page or run code that is dependent upon data from that `context`. A template executes the `apply` function when the `apply` function has the following structure.

```typescript
apply(context: Object, template: Function) => Promise<boolean> | void
```

The first parameter is the `context`; the payload returned from the server-side code of the **Serverside Code** tab in the form of a JavaScript object.

The second parameter is `template`; a function that expects the `context` as an argument to resolve with the Handlebars template, returning the generated HTML content.

The `apply` function can return a `Promise` that delays the rendering of the template until the `Promise` resolves. If you return a `Promise`, the `OnTemplateDisplayEnd` event fires when the `Promise` resolved, making it easy for developers to delay the `OnTemplateDisplayEnd` event to whenever certain DOM elements become available on a page. If your `apply` function does not return a `Promise`, the `OnTemplateDisplayEnd` event fires immediately, subsequently causing the built-in [Campaign Stats Gear](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-stats-tracking.md#use-with-handlebars-and-clientside-code) to begin tracking campaign statistics immediately.

**note:** As mentioned in the [Campaign Stats Tracking](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-stats-tracking.md#use-with-handlebars-and-clientside-code) documentation, the `OnTemplateDisplayEnd` event is what triggers the built-in Campaign Stats Gear to begin tracking campaign statistics.

#### Template

The `template` function passes the `context` to the pre-compiled **Handlebars HTML** and returns the HTML generated by populating the template fields with the `context` object attributes. The `template` function has the following structure.

```typescript
template(context: Object) => string
```

**note:** For information regarding content zones, refer to the [Content Zones](https://developer.salesforce.com/docs/marketing/web-integration/content-zones.md) and [Server TypeScript](https://developer.salesforce.com/docs/marketing/personalization/guide/template-server-typescript.md) documentation.

---

### Reset

The `reset` function is called to remove the template from the DOM. Personalization does not call the `reset` function on your website from the Personalization module of the Salesforce Interactions SDK at any stage of a campaign's lifecycle. However, the Personalization Visual Editor uses the `reset` function when developing a template.

If the template is meant to replace content on the page, the proper implementation of this method is to restore the replaced content.

The `reset` function has the following structure.

```typescript
reset(context: Object, template: Function) => void
```

**important:** It is not advised to call your defined `reset` function directly, such as serving as the handler for a close icon.

### Control

The `control` function is called for users in the control group of the campaign to handle sending stats and also render content for those users. The `control` function can return a `Promise` that delays running the function's code until the `Promise` resolves, similar to using a `Promise` in the `apply` function.

The `control` function has the following structure.

```typescript
control(context: Object) => Promise<boolean> | void
```

<!-- document id=fb1f56ef5e57333cad47a49601e8e14afc7e835459831e6d7d0bb8e9f7a08628 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/templates/template-response-simulator.md -->

# Template Response Simulator

When developing a template in the Marketing Cloud Personalization UI, you can simulate a template response without leaving the development interface. You can simulate the template response for an event by providing details about the event, such as the user a campaign renders for and the current item in the event. This article outlines the components of the simulator and describes how you can leverage it to aid template development and testing.

## Simulator Components

The payload simulator is in the **Payload Preview** tab of the Template Editor and allows you to define the following components to simulate a campaign response.

- **User**: In the **User** field, you can search for any user profile in Personalization by their `userId` or username. The template response payload references the user you select in this field.
- **Current Item Type & Current Item**: These fields are only necessary if the campaign requires contextual data such as the item currently viewed, which is a common requirement for recipes like co-browse, co-buy, and similar items. You can configure a **Current Item** only after selecting the **Current Item Type**.

  ![Template Response Simulator](https://developer.salesforce.com/media/campaign-development/template-response-simulator.png)

## Simulating a Template Response

To simulate a template, do the following.

1. Enter the necessary simulator information in the **User**, **Current Item Type**, and **Current Item** fields.
2. Enter the template configuration (the information a business user would provide while constructing a campaign).

You can now view the template payload response in the **Payload Preview** section of the **Payload Preview** tab.

Since the template configuration section has the **Auto Render** checkbox selected by default, any changes made to the template configuration or within the **Simulator** pane re-renders the template response payload. If you unselect **Auto Render**, you need to click **RENDER** to refresh the template payload response every time you change any of the values in the template configuration or the Simulator pane.

<!-- document id=8e1b3ecb29b6e7426c7c6ab76192c3a9214222e1b27ecfd11101a713edebb10a url=/developer/current/en-us/personalization/personalization/guides/campaign-development/templates/template-server-typescript.md -->

# Template Server TypeScript

The **Serverside Code** tab in the Template Editor is where developers define code in TypeScript that runs on the server before returning a template. While this tab is available on both Web and Server-Side templates, Server-Side templates only have the **Serverside** Code tab and does not have the **Handlebars**, **CSS**, or **Clientside Code** tabs. Additionally, Server-Side templates don't have a content zone to target; you can only use them in the corresponding Server-Side Campaigns.

## Template Context Schema and Code Execution

The content displayed in a template is driven by data that we refer to as the context. The Server-Side code (written in TypeScript) is responsible for defining this context and serves two primary purposes:

1. Define the template interface configuration schema, which constructs the shape of the template's context
2. Executes code on the server that allows for the population of the context with additional data available in Marketing Cloud Personalization and any enabled Gears extensions

The template's `context` is a payload that returns from the server-side containing the necessary catalog and user data to render a campaign. In a Server-Side template, Personalization can issue this data as a JSON payload. In a web template, the `context` derived on the server is transmitted to the client browser. On the browser, the client-side JavaScript can decide what to do with the `context`, including using the values from `context` to dynamically build the HTML from the template's **Handlebars** tab and rendering logic defined in the **Clientside Code** tab.

## Template Class Structure

A template is a class that extends `CampaignTemplate` and implements a single `run` method.

```typescript
export class ExampleTemplate implements CampaignTemplate {
  @title("Example Field")
  header: string;

  run(context: CampaignComponentContext) {
    return {};
  }
}
```

## Template Interface Configuration

The properties of the template's class are used to generate a configuration UI that is displayed to a business user when working in the campaign editor. The business user fills out the template's configuration inputs in the Campaign Editor to contextualize the template.

Examples of items a template developer could expose to a business user in the template configuration include:

- Text input fields for experience messaging
- Recipe dropdown selectors for ML-driven recommendation campaigns
- Display timing logic
- Styling (text color, image background, font, and so on.)

For more information about the configuration system and all possible UI inputs, see [Interface & Template Configuration](https://developer.salesforce.com/docs/marketing/custom-interface-template-configuration/decorators.md).

## Content Zones

A content zone is a "hot spot" for personalization. When configuring a template, the template developer defines the content zones where the template is eligible for use through the **Content Zones in Template** selector in the bottom-left corner of the Template Editor. A business user can then only use a template for the area on the site that it was designed for. If a template has more than one content zone assigned (think of a Recommendations row that could exist on many pages), the business user can select which content zone they intend to target in the actual campaign.

Content Zones are defined and mapped as part of the sitemap. A content zone can contain a CSS selector, which directly points to an element on that page. However, since a CSS selector is not required, the content zone can instead be used as a "logical" or "global" target on a page. For example, if a page is rendering popups that appear on top of the page, its rendering is not linked to any specific CSS selector. If you would like to add additional content zones after the initial implementation, you can easily add them via the sitemap editor in the Personalization visual editor. Adding content zones via the in-app Sitemap Editor **WILL NOT** allow them to appear as a selection option in the template editor.

**important:** Server-Side templates do not have a content zone selector in the template editor screen as server-side campaigns do not need content zones for campaign targeting. However, you can manually configure content zones on server-side templates to tie server-side campaigns to specific locations on the site. For more information on content zones with server-side campaigns, see [Server-Side Campaigns and Content Zones](https://developer.salesforce.com/docs/marketing/personalization/server-side-campaigns-templates/server-side-campaigns-content-zones.md#server-side-campaigns).

## Run

The `run` function executes on Personalization servers when the template prepares to construct a JSON response. Here, you can manipulate the values of the context or add additional values not configured by the end user.

```typescript
run(context: CampaignComponentContext) => Object)
```

The object returned by the `run` function is merged with the context from the configured template. The return value of the `run` function overwrites any fields from the template that share the same key.

```typescript
import { getDataFromGear } from "mygear";

export class MyTemplate implements CampaignTemplate {

    exampleField: string = "default value";

    run(context:CampaignComponentContext) {
        return {
            additionalData: getDataFromGear(this.exampleField);
        };
    }
}
```

### this Object

You can access any properties defined in the head of the class by prepending the variable with `this`. All properties defined are added to the template's local instance of `this` in the `run` function. Any parameters created can be accessed for processing in the `run` function.

### Context Object

The `context` object is an instance of `CampaignComponentContext`, the primary way to interact with Personalization properties exposed to templates. The `context` object enables the template author to access the properties defined in the class. For more information on the `context` object, refer to the [CampaignComponentContext](https://salesforce-marketingcloud.github.io/mc-personalization-core-api-typedocs/interfaces/campaigncomponentcontext.html) documentation. The `context` object also allows access to the `user` object, including user attributes and services like `recommendations` if enabled (`context.services.recommendations`).

All properties of the template's class are used to generate a configuration UI. This configuration UI is then displayed to a business user when selecting the template for use in a Personalization campaign. The business user then completes the template's configuration inputs in the Campaign Editor to contextualize the template.

For more information on the configuration system and all possible UI inputs, refer to the [Interface & Template Configuration](https://developer.salesforce.com/docs/marketing/custom-interface-template-configuration.md) documentation.

## Server-Side TypeScript Example

The following code sample is a server-side template that allows business users to configure a comma-separated list of user attributes to return in the payload. You can configure the list of attributes to return in the campaign that uses the template.

```typescript
export class NewTemplate implements CampaignTemplateComponent {
  @title("User Attributes To Retrieve")
  @subtitle("Contents must be a Comma separated list")
  userAttributes: string;

  run(context: CampaignComponentContext) {
    let attrs = this.userAttributes.split(",");
    let attributesToSend = {};
    attrs
      .filter((value) => {
        return context.user.attributes.hasOwnProperty(value);
      })
      .map((attributeName) => {
        attributesToSend[attributeName] = {
          value: context.user.attributes[attributeName],
        };
      });

    return {
      attributes: attributesToSend,
    };
  }
}
```

## See Also

- [`CampaignComponentContext` Documentation](https://salesforce-marketingcloud.github.io/mc-personalization-core-api-typedocs/interfaces/campaigncomponentcontext.html)

<!-- document id=17b9563c6b627d2e53eb68a4ac60aefb736d8e9206fb6665ea76d5bffc232719 url=/developer/current/en-us/personalization/personalization/guides/web-integration/personalization-sitemap.md -->

# The Personalization Sitemap

In traditional web development, a sitemap (or site map) is a hierarchical list of pages of a website and the relationships between them. In Personalization, a **Sitemap** represents the JavaScript configuration through which the Personalization web-channel solution architecture is implemented. A Personalization developer must configure a Sitemap to be able to collect the user interactivity data on all desired website "page types" and support the business requirements to:

- Develop [web templates](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/personalization-template-system.md) that enable the delivery of [web channel campaigns](https://developer.salesforce.com/docs/marketing/personalization/campaign-development.md) to targeted prospects and customers.
- Enrich the company knowledge and data profiles of customers, prospects, products, and site content assets based on website visitor actions.
- Enable the development of in-depth behavioral analytics and machine learning capabilities.

## Sitemap JavaScript Functionality

The JavaScript configured in a Personalization Sitemap provides the functionality that enables Personalization to identify the following.

- **User Profiles:** Identity, using a known user ID or anonymous user tracking ID, who interacts with the website, enabling user profile development based on browsing actions and existing data drawn from company systems.
- **Page Types:** The type of page the user is browsing (Home page, Product page, and so on).
- **Attributes:** Detailed data about the user's attributes and the business objects that the user is interacting with, such as product or service catalog items or other web content (blogs, articles, and so on).
- **Content Zones:** Areas of each web page type that Personalization can monitor and target for personalized user engagement opportunities.
- **Events:** Types of user activity to listen for that triggers events to Personalization.

Always remember to configure the JavaScript for a Personalization Sitemap before developing Personalization [web templates](https://developer.salesforce.com/docs/marketing/personalization/campaign-development/personalization-template-system.md) that support customer engagement [campaigns](https://developer.salesforce.com/docs/marketing/personalization/campaign-development.md) based on customer and prospect web channel interactions.

For more information about any of the preceding topics, see:

- [Capturing User and Account Attributes](https://developer.salesforce.com/docs/marketing/personalization/guide/capturing-user-account-attributes.md)
- [User Identity Mapping](https://developer.salesforce.com/docs/marketing/personalization/guide/user-identity-mapping.md)
- [Page Types](https://developer.salesforce.com/docs/marketing/personalization/guide/page-types.md)
- [Attributes](https://developer.salesforce.com/docs/marketing/personalization/data-modeling/attributes.md)
- [Capturing User and Account Attributes](https://developer.salesforce.com/docs/marketing/personalization/guide/capturing-user-account-attributes.md)
- [Content Zones](https://developer.salesforce.com/docs/marketing/personalization/guide/content-zones.md)

## Sitemap Blueprint

As part of the Personalization discovery process, a solution architect works with the Personalization customer to understand the business context and determine the web-channel solution architecture that the Sitemap configuration needs to implement. The discovery process produces a **Sitemap Blueprint** that provides the Sitemap developer with the following information.

- **Site Catalog:** The brands, products, services, or other website content such as articles and blogs that Personalization needs to monitor. The site catalog also includes the specifications of product categories such as "home goods", "camping", and "winter wear", along with individual catalog objects such as color, gender, and keyword.
- **Site Architecture:** The structure of the website and layout of page types. A large online retailer could have hundreds or even thousands of individual product pages, but the structural layout of each product page type is relatively similar. As a Sitemap developer, you must understand the website's architecture, and the types of pages that require configuration in the Sitemap.
- **Attribute Model:** Attributes are used in a Sitemap to collect and store additional custom data for each relevant business object type. Business objects with associated attributes include users, accounts, catalog items, orders, and line items. Attributes can also include metadata on the attribute value, such as the attribute data origin/provider, sensitivity classification (PII, sensitive, non-sensitive), and the attribute value refresh date. Attributes provide additional information to Personalization that campaign developers can use for targeting, segmentation, and machine learning purposes. Part of the discovery process includes developing an attribute model schema that specifies the individual attribute name/value pairs, associated metadata, and the purpose of each attribute.
- **Web Engagement Use Cases:** The Sitemap Blueprint specifies the use cases that explain how the business wants to engage with its prospects and customers through the website. The Sitemap Blueprint needs to include the website's [Content Zone](https://developer.salesforce.com/docs/marketing/personalization/guide/content-zones.md) requirements.
- **Site Events:** The types of actions performed by users on the website to be sent to Personalization for segmentation, campaign targeting, or behavioral tracking (machine learning). For more information on capturing events and sending them to Personalization via API, see [Sitemap Implementation](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemap-implementation.md) and [Event API](https://developer.salesforce.com/docs/marketing/personalization/event-api/event-api.md).

## Sitemap Integration and Configuration

The Personalization Sitemap system is deployed by and executes within a Beacon API and the Personalization module of the Salesforce Interactions SDK. A Sitemap is integrated into a site by establishing a connection from the site to Personalization through a `<script>` tag added in the site header, as shown in the following example.

```html
<script src="https://<accountName>.<instance>.evergage.com/scripts/evergage.min.js"></script>
```

In the preceding example, `accountName` indicates your Personalization account name and `instance` indicates your Personalization instance identifier. You can retrieve these details by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if your Gears URL is `https://demo.us-1.evergage.com/`, then your account name is `demo` and `us-1` is your instance identifier.

The Sitemap is configured using the **Sitemap Editor** included with the Personalization Visual Editor. After the Web SDK script tag has been added to a site, you can use the Sitemap Editor to configure the site to support the Personalization web channel solution. Using the Sitemap Editor, you can leverage the JavaScript functions provided by the Personalization Web SDK library and execute that functionality through HTTP requests to the Personalization **Event API**.

**note:** Based on the validity and configuration of the Sitemap, HTTP requests are sent automatically by the Web SDK. Additionally, the Web SDK provides a `sendEvent` function in each namespace that can be called to send events through the [Event API](https://developer.salesforce.com/docs/marketing/personalization/event-api/event-api.md).

### Getting Started with Site Mapping

For guidance on getting started with Personalization Site Mapping and the Sitemap Editor, see [Getting Started with Site Mapping](https://developer.salesforce.com/docs/marketing/personalization/guide/sitemapping-getting-started.md).

<!-- document id=ec31934fe754fd52bbb43b417d96bd0463d1ec7fee9de783cf8d7506c8926587 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/templates/campaign-stats-tracking.md -->

# Tracking Personalization Web Campaign Statistics

The Campaign Stats Gear tracks impressions, clickthroughs, dismissals, and recommended items on your Marketing Cloud Personalization campaigns. These statistics give you insight into the effectiveness of these campaigns and help you decide where to adjust your campaigns for better results.

**note:** Most organizations use third-party analytics software to track campaign effectiveness, in addition to using Personalization Campaign Statistics. In such cases, it is possible that Personalization campaign statistics differ from statistics gathered via third-party software. This difference is mainly because tracking parameters and their definitions on Personalization can vary from how they're defined, handled, and tracked in third-party systems.

A campaign's DOM structure must meet specific requirements to correctly track statistics in Personalization.

## Background

Campaign statistics are necessary for analytics in Personalization, analytics events emitted to external systems, segment creation, campaign targeting, and machine learning optimization.

## HTML Specification

Use the following HTML data attributes in order to properly track campaign statistics using the Campaign Statistics gear.

| Attribute                      | Description                                                                                                                                                                                                                                                                                                | Use in Template Handlebars                |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `data-evg-campaign-id`         | The ID of the campaign. This attribute must be specified for any client-rendered web campaigns.                                                                                                                                                                                                            | `data-evg-campaign-id="{{campaign}}"`     |
| `data-evg-experience-id`       | The ID of the experience. This attribute must be specified for any client-rendered web campaigns. By default, clicks on any `<a>` tags nested within an element containing this attribute are tracked.                                                                                                     | `data-evg-experience-id="{{experience}}"` |
| `data-evg-user-group`          | The group that the user belongs to. This group is either the test or control group.                                                                                                                                                                                                                        | `data-evg-user-group="{{userGroup}}"`     |
| `data-evg-clickthrough`        | Indicates that this element is clickable. This attribute can be added to any element with no value to indicate that it should generate a clickthrough when clicked. Note that it is unnecessary to add this value to `<a>` tags that are children of an element with the `data-evg-experience-id` element. | `data-evg-clickthrough`                   |
| `data-evg-ignore-clickthrough` | Indicates that this element is clickable, but should not have a clickthrough tracked for it. This attribute can be added with no value to any element or ancestor of the clickable element.                                                                                                                | `data-evg-ignore-clickthrough`            |
| `data-evg-dismissal`           | Indicates that this element is dismissible. This attribute can be added to any element with no value to indicate that it should generate a dismissal when clicked.                                                                                                                                         | `data-evg-dismissal`                      |
| `data-evg-item-id`             | The ID of the item represented by this element and its child elements. This ID (and the type specified by `data-evg-item-type`) must already be tracked in the Personalization catalog. Adding this attribute to an element, along with `data-evg-item-type`, binds and tracks clickthroughs.              | `data-evg-item-id="{{id}}"`               |
| `data-evg-item-type`           | The type of the item represented by this element and its child elements. This type (and the ID specified by `data-evg-item-id`), must already be tracked in the Personalization catalog. Adding this attribute to an element, along with `data-evg-item-id`, binds and tracks clickthroughs.               | `data-evg-item-type="{{itemType}}"`       |

**note:** - To track promotions accurately using this gear, your campaign template must include the `data-evg-item-id` and `data-evg-item-type` attributes. The updated Einstein Decisions template includes these attributes by default. Cloning this template and applying it to your campaign enables promotion tracking by default.
- Personalization will display campaign statistics for unpublished campaigns that you're testing. Although unpublished, the Campaign Stats Gear can still track and increment campaign statistics on these campaigns.

### Example for tracking a clickthrough (Handlebars)

```handlebars
<!-- Default click tracking using anchor tag -->
<div
  id="evg-home-hero-promo"
  data-evg-campaign-id="{{campaign}}"
  data-evg-experience-id="{{experience}}"
  data-evg-user-group="{{userGroup}}"
>
  <div class="evg-content">
    <div class="evg-promo">
      {{header}}
    </div>
    <div class="evg-body">
      {{bodyText}}
    </div>
    <a class="evg-cta" href="{{destinationURL}}">
      {{ctaText}}
    </a>
  </div>
</div>

<!-- Click tracking using data-evg-clickthrough -->
<div
  id="evg-home-hero-promo"
  data-evg-campaign-id="{{campaign}}"
  data-evg-experience-id="{{experience}}"
  data-evg-user-group="{{userGroup}}"
>
  <div class="evg-content">
    <div class="evg-promo">
      {{header}}
    </div>
    <div class="evg-body">
      {{bodyText}}
    </div>
    <button class="evg-cta" data-evg-clickthrough>
      {{ctaText}}
    </button>
  </div>
</div>
```

### Examples for disabling a clickthrough without tracking a dismissal (Handlebars)

```handlebars
<!-- Directly on the clickable -->
<div
  id="evg-home-hero-promo"
  data-evg-campaign-id="{{campaign}}"
  data-evg-experience-id="{{experience}}"
  data-evg-user-group="{{userGroup}}"
>
  <div class="evg-content">
    <div class="evg-promo">
      {{header}}
    </div>
    <div class="evg-body">
      {{bodyText}}
    </div>
    <a class="evg-cta" data-evg-ignore-clickthrough href="{{destinationURL}}">
      {{ctaText}}
    </a>
  </div>
</div>

<!-- On parent element of the clickable element -->
<div
  id="evg-home-hero-promo"
  data-evg-campaign-id="{{campaign}}"
  data-evg-experience-id="{{experience}}"
  data-evg-user-group="{{userGroup}}"
>
  <div class="evg-content" data-evg-ignore-clickthrough>
    <div class="evg-promo">
      {{header}}
    </div>
    <div class="evg-body">
      {{bodyText}}
    </div>
    <a class="evg-cta" href="{{destinationURL}}">
      {{ctaText}}
    </a>
  </div>
</div>
```

### Example for tracking a dismissal (Handlebars)

```handlebars
<div
  id="evg-email-capture-popup"
  data-evg-campaign-id="{{campaign}}"
  data-evg-experience-id="{{experience}}"
  data-evg-user-group="{{userGroup}}"
>
  <div
    class="evg-popup"
    style="background-image:url('{{imageUrl}}'); color: {{textColor.hex}}; font-family: {{font}}"
  >
    <div class="evg-close" data-evg-dismissal>
    </div>
  </div>
</div>
```

### Example for a recommendation campaign (Handlebars)

```handlebars
<div id="evg-product-recs" data-evg-campaign-id="{{campaign}}" data-evg-experience-id="{{experience}}" data-evg-user-group="{{userGroup}}">
    <div class="evg-recs-title">
        {{title}}
    </div>
    {{#each items}}
    <div class="evg-item" data-evg-item-id="{{id}}" data-evg-item-type="{{../itemType}}">
        <a href="{{attributes.url.value}}">
            <img src="{{attributes.imageUrl.value}}" alt="{{attributes.name.value}}"/>
        </a>
            <div>
                <span><a href="{{attributes.url.value}}">{{attributes.name.value}}</a></span>
            </div>
        <div>
            ${{attributes.price.value}}
        </div>
    </div>
    {{/each}}
</div>
```

## Use with Handlebars and Client-side Code

When a campaign is returned to the web browser, the user is in either a "Test" group or the "Control" group. If the user is in a "Test" group, a template's client-side code executes the `apply()` function. Likewise, if the user is in the "Control" group, a template's client-side code executes the `control()` function. Both functions can return either a `Promise` or `void`. For more information, see the [Template Client JavaScript](https://developer.salesforce.com/docs/marketing/personalization/guide/template-client-javascript.md) documentation.

If the `apply()` function doesn't return a `Promise`, Personalization dispatches the `Evergage.CustomEvents.OnTemplateDisplayEnd` event immediately, subsequently triggering the Campaign Stats Gear to begin tracking campaign statistics even before the template may have fully rendered.

For more information on the `apply()` function, refer to the [Template Client JavaScript](https://developer.salesforce.com/docs/marketing/personalization/guide/template-client-javascript.md#apply) documentation.

**note:** The "Control" experience _does not_ necessarily need to render HTML into the DOM for Campaign Stats Gear to track a "Control" impression. For instance, an impression stat is tracked immediately if the `control()` function does not return a `Promise`.

The following code samples are examples of how you can return a Promise in an `apply()` function using [the `pageElementLoaded` method from `DisplayUtils`](https://developer.salesforce.com/docs/marketing/personalization/web-campaigns-templates/web-template-display-utilities.md) in the `SalesforceInteractions` and `Evergage` namespaces.

```javascript
function apply(context, template) {
  const contentZoneSelector = SalesforceInteractions.mcis.getContentZoneSelector(
    context.contentZone,
  );

  return SalesforceInteractions.DisplayUtils.bind(buildBindId(context))
    .pageElementLoaded(contentZoneSelector)
    .then((element) => {
      const html = template(context);
      SalesforceInteractions.cashDom(element).html(html);
    });
}
```

```javascript
function apply(context, template) {
  const contentZoneSelector = Evergage.getContentZoneSelector(context.contentZone);

  return Evergage.DisplayUtils.bind(buildBindId(context))
    .pageElementLoaded(contentZoneSelector)
    .then((element) => {
      const html = template(context);
      Evergage.cashDom(element).html(html);
    });
}
```

The following code samples are examples of how you can return a Promise in an `apply()` function using a `new Promise`.

```javascript
function apply(context, template) {
  const contentZoneSelector = SalesforceInteractions.mcis.getContentZoneSelector(
    context.contentZone,
  );

  return new Promise((resolve) => {
    const startTime = Date.now();
    const contentZoneElement = () => SalesforceInteractions.cashDom(contentZoneSelector);

    let tryInterval = setInterval(() => {
      if (contentZoneElement().length > 0) {
        clearInterval(tryInterval);
        resolve(contentZoneElement());
      }
    }, 100);
  }).then((element) => {
    if (element == null) return; // if we remove the timeout case, this can be removed too

    const html = template(context);
    SalesforceInteractions.cashDom(element).html(html);
  });
}
```

```javascript
function apply(context, template) {
  const contentZoneSelector = Evergage.getContentZoneSelector(context.contentZone);

  return new Promise((resolve) => {
    const startTime = Date.now();
    const contentZoneElement = () => Evergage.cashDom(contentZoneSelector);

    let tryInterval = setInterval(() => {
      if (contentZoneElement().length > 0) {
        clearInterval(tryInterval);
        resolve(contentZoneElement());
      }
    }, 100);
  }).then((element) => {
    if (element == null) return; // if we remove the timeout case, this can be removed too

    const html = template(context);
    Evergage.cashDom(element).html(html);
  });
}
```

## Use without Handlebars and Client-side Code

If your site does not use Handlebars and Client-side Code in a Personalization template to render campaigns, you can still use the Campaign Stats Gear to track campaign statistics.

When you are ready to track an impression for a Personalization campaign, dispatch an `SalesforceInteractions.mcis.CustomEvents.OnTemplateDisplayEnd` event or `Evergage.CustomEvents.OnTemplateDisplayEnd` event, depending on the SDK namespace you're using, with the following `detail`.

```typescript
{
  payload: {
      campaign: string,
      experience: string,
      userGroup: string
  }
}
```

The following code samples depict how you can dispatch a `SalesforceInteractions.mcis.CustomEvents.OnTemplateDisplayEnd` or `Evergage.CustomEvents.OnTemplateDisplayEnd` event with an example payload.

```javascript
document.dispatchEvent(
  new CustomEvent(window.SalesforceInteractions.mcis.CustomEvents.OnTemplateDisplayEnd, {
    detail: {
      payload: {
        campaign: "abc12",
        experience: "def34",
        userGroup: "Test",
      },
    },
  }),
);
```

```javascript
document.dispatchEvent(
  new CustomEvent(window.Evergage.CustomEvents.OnTemplateDisplayEnd, {
    detail: {
      payload: {
        campaign: "abc12",
        experience: "def34",
        userGroup: "Test",
      },
    },
  }),
);
```

## Control Click Tracking

In order to track clicks in the control group, the data attributes must be added to elements that are either rendered by the campaign, or exist on site and a user in the control group would see. See the following code samples for guidance on adding these attributes in the `control()` function.

```javascript
function control(context) {
  SalesforceInteractions.cashDom("SELECTOR").attr({
    "data-evg-campaign-id": context.campaign,
    "data-evg-experience-id": context.experience,
    "data-evg-user-group": context.userGroup,
  });
}
```

```javascript
function control(context) {
  Evergage.cashDom("SELECTOR").attr({
    "data-evg-campaign-id": context.campaign,
    "data-evg-experience-id": context.experience,
    "data-evg-user-group": context.userGroup,
  });
}
```

If you're using a DisplayUtil such as `pageElementLoaded` in the template's `apply` function, then it is also _strongly suggested_ that you use it similarly in the `control` function to ensure that campaign stats are being tracked the same way.

```javascript
function control(context) {
  const contentZoneSelector = SalesforceInteractions.mcis.getContentZone(context.contentZone);
  return SalesforceInteractions.DisplayUtils.bind(`${context.campaign}:${context.experience}`)
    .pageElementLoaded(contentZoneSelector)
    .then((element) => {
      SalesforceInteractions.cashDom("SELECTOR").attr({
        "data-evg-campaign-id": context.campaign,
        "data-evg-experience-id": context.experience,
        "data-evg-user-group": context.userGroup,
      });
    });
}
```

```javascript
function control(context) {
  const contentZoneSelector = Evergage.getContentZone(context.contentZone);
  return Evergage.DisplayUtils.bind(`${context.campaign}:${context.experience}`)
    .pageElementLoaded(contentZoneSelector)
    .then((element) => {
      Evergage.cashDom("SELECTOR").attr({
        "data-evg-campaign-id": context.campaign,
        "data-evg-experience-id": context.experience,
        "data-evg-user-group": context.userGroup,
      });
    });
}
```

## Sending Campaign Stats without the Campaign Stats Gear

`SalesforceInteractions.mcis.sendStat` and `Evergage.sendStat` accept a `CampaignStatEvent`.

### CampaignStatEvent

```typescript
{
  campaignStats: CampaignStat[];
}
```

### CampaignStat

```typescript
{
  experienceId: string,
  stat: 'Impression' | 'Clickthrough' | 'Dismissal',
  control: boolean,
  catalog: { [itemTypeKey: string]: string[] }
}
```

The following code samples depict how you can use `SalesforceInteractions.mcis.sendStat` or `Evergage.sendStat` to send a `CampaignStatEvent` event with recommended items.

```javascript
const stat = {
  experienceId: "def34",
  stat: "Impression",
  control: false,
  catalog: {
    Product: ["product1", "product2"],
  },
};

SalesforceInteractions.mcis.sendStat({ campaignStats: [stat] });
```

```javascript
const stat = {
  experienceId: "def34",
  stat: "Impression",
  control: false,
  catalog: {
    Product: ["product1", "product2"],
  },
};

Evergage.sendStat({ campaignStats: [stat] });
```

<!-- document id=945fe1812c40e411ad08c2d53c3714851b2784f39468998abca97f46f479380b url=/developer/current/en-us/personalization/personalization/guides/campaign-development/advanced-dynamic-message-content/use-advanced-dynamic-message-content.md -->

# Use Advanced Dynamic Message Content

You can use ADMC in the message content of your Mobile Data Campaigns and while creating Open-Time Email Campaigns and item templates. With ADMC, you can:

- Access the current product, article, blog, or category a visitor is currently viewing
- Access products in a visitor's cart
- Access multiple items by ID
- Specify the minimum and maximum number of items to be returned in campaigns
- Access items that visitors have viewed, sorted by recency, and not restricted to their current visit
- Match the least viewed or purchased items globally
- Sort matching items by name, price, or other fields to present the most relevant items to the campaign audience
- Match items based on a statistic from a lookback period other than the default one week
- Match only items that meet certain conditions, such as those with image URLs or containing specific keywords like "clearance"

## Currently Viewed Item or Category

To access the item (Product, Article, or Blog) the visitor is currently viewing, use the `$page.item` variable. To access the category the visitor is currently viewing (or the category of the Item currently being viewed), use the `$page.category` variable. The `$page.category` variable can either be used directly within the message content or passed to a global or user query using `$itemOptions.withCategory($page.category.id)`. You can also use `$page.brand` and `$page.gender` to include the brand and gender. If there’s more than one applicable category, brand, or gender, Personalization shows the first one found on the page (based on how the page is coded).

For more information, see [Item Options](#item-options).

## Products Currently in Cart

To show data about the current items contained in the visitor's shopping cart, use `$tools.user.order.current()`.

Or to show only the list of unique products in the visitor's cart, use `$tools.user.order.currentItems()`.

## Specific Items

A single, specific item can be promoted using the **Static** subtab of the **Promoted Content** tab, but to promote more than one specific Item, use the `$tools.global.products.findById` function as shown in the following example.

```html
$tools.global.products.findById("501")
```

You can replace `products` with `categories`, `brands`, or other groupings configured in your Personalization Catalog, to show items in those groupings. For example, to show brands, use `$tools.global.brands.findById`. To show multiple items, use `$tools.global.products.findByIds`, which works similarly and accepts a list of up to 10 IDs. This function returns all items found in order by ID. Items that aren’t found are skipped.

```html
$tools.global.products.findByIds( ["501", "993"])
```

## User’s Recently Viewed Items

For options that can be passed to the “viewed” function to specify minimum and maximum results, sorting, filtering, and other options, see [Item Options](#item-options).

To show items the visitor has recently viewed, with last viewed item first, the `$tools.user.products.viewed` function can be used. You can access additional item types by replacing `products` with `categories`, `brands`, or other groupings configured in your Personalization Catalog. The lookback time period can’t be adjusted and is always this visit.

## User’s Most Viewed or Purchased Items

For options that can be passed to the `viewCount`, `viewTime`, and `purchaseCount` functions to specify minimum and maximum results, sorting, filtering, lookback time period, and other options, see [Item Options](#item-options).

To show items that the visitor has viewed the most times, use the `$tools.user.products.viewCount` function.

To show items that the visitor has spent the most time viewing, use the `$tools.user.products.viewTime` function. Additional item types can be shown by replacing “products” with “categories”, “brands”, or other groupings configured in your Personalization Catalog. For example, `$tools.user.brands.viewTime`.

To show items that the visitor has purchased the most times, use the `$tools.user.products.purchaseCount` function.

## Most Viewed or Purchased Items Globally

To access Items that have been viewed the most times globally, use the `$tools.global.products.viewCount` function.

To access Items that visitors have spent the most time viewing globally, use the `$tools.global.products.viewTime` function. Additional item types can be shown by replacing “products” with “categories”, “brands”, or other groupings configured in your Personalization Catalog. For example, `$tools.global.brands.viewTime`.

To access Items purchased the most times globally, use the `$tools.global.products.purchaseCount` function.

## Most Recently Published Items Globally

For options that can be passed to the `publishedDate` function to specify minimum and maximum results, sorting, filtering, lookback time period, and other options, see [Item Options](#item-options).

To find items were recently published, sorted by published date, use the `$tools.global.products.publishedDate` function.

## Item Options

The `$tools.(user|global).products.(viewed|viewCount|viewTime|purchaseCount)` query functions can all be passed a set of item options to refine the results. Item options can specify minimum and maximum results, lookback time period, filtering, sorting, and so on.

Item options are created by calling multiple functions on the `$itemOptions` object. For example, to create a set of item options that shows the top three items people spent the most time viewing today, sorted by product name, you could use:

```html
$tools.global.viewTime($itemOptions.minItems(3).maxItems(3).time($time.today()).displaySort($productSort.name()))
```

### Min/Max Results

By default, a message containing advanced dynamic queries renders only if there is at least 1 result, and a maximum of 5 results are returned. You can increase the minimum using `$itemOptions.minItems(n)` and the maximum using `$itemOptions.maxItems(n)`. You can’t increase the maximum beyond 10.

For example, to render the message only if there are at least 3 results and to limit the number of results shown to 3, use:

```html
$itemOptions.minItems(3).maxItems(3)
```

### Lookback Time Period

By default, queries consider item data from the past week. To use a different lookback period, use the `$itemOptions.time` function. For example, to consider today only, use:

```html
$itemOptions.time($time.today())
```

The following functions are provided by the `$time` singleton object:

- `today` - today
- `thisWeek` - current calendar week (with Monday as first day of week)
- `thisMonth` - current calendar month
- `since(date)` - since the specified date; date format is `mm/dd/yyyy` (for example, `07/07/2017`)
- `lastNDays(n)` - last n days, including today; `lastNDays(1)` would mean today and yesterday
- `allTime` - don’t define a specific date range

### Filtering by Category, Brand or Gender

To filter results to contain products with a particular category, use `$itemOptions.withCategory(categoryId)`. For example, to filter by the category the visitor is viewing, use:

```html
$itemOptions.withCategory($page.category.id)
```

To filter by the visitor's most purchased category, use:

```html
$itemOptions.withCategory($tools.user.categories.purchaseCount()[0])
```

To filter results to contain only products with a specific brand, use `$itemOptions.withBrand(brandId)`. For example, to filter by visitor's most purchased brand, use:

```html
$itemOptions.withCategory($tools.user.brands.purchaseCount()[0])
```

To filter by gender:

```html
$itemOptions.withGender($page.gender)
```

### Filtering Based on Item Fields

Results can be filtered based on Item field values using any of the following conditions:

- Field has a value
- Field doesn’t have a value
- Field’s value contains a substring
- Field’s value doesn’t contain a substring

To only include Items that have image URLs, use:

```html
$itemOptions.whereImageUrl().exists()
```

To only include Items that have “clearance” in their descriptions, use:

```html
$itemOptions.whereDescription().contains(“clearance”)
```

The following functions are available, each corresponding to a different field:

- `whereName`
- `whereCreated`
- `wherePublished`
- `whereDescription`
- `whereUrl`
- `whereImageUrl`
- `wherePriceDescription` (Products only)

The preceding functions correspond to the four types of conditions:

- `exists`
- `doesNotExist`
- `contains(substring)`
- `doesNotContain(substring)`

**note:** The functions `contains` and `doesNotContain` are case-insensitive.

### Query Result Order

By default, query results are returned in descending order with the most popular or most recently viewed Items listed first. To reverse the order, and return the least popular or least recently viewed Items first, use:

```html
$itemOptions.descending()
```

### Display Sorting

To sort the results for display, use the `$itemOptions.displaySort` function. Use `$productSort` for products, `$articleSort` for articles, and `$blogSort` for blogs. For example, to sort the results by product name, use:

```html
$itemOptions.displaySort($productSort.name())
```

The following functions are available on `$productSort`, corresponding to different product fields:

- `name`
- `price`

The following functions are available on `$articleSort` and `$blogSort`, corresponding to different article or blog fields:

- `name`
- `publishedDate`

By default, display sorting is done in ascending order. To use descending order instead, you can use the `descending` function:

```html
$itemOptions.displaySort($productSort.name().descending())
```

### Include Items Being Viewed or Products in Cart

By default, items the visitor is viewing are excluded from query results. To include them, use:

```html
$itemOptions.includeItemsBeingViewed()
```

By default, Products that are currently in the visitor's cart are excluded from query results. To include them, use:

```html
$itemOptions.includeItemsInCart()
```

### Exclude Items Previously Viewed or Purchased

By default, items the visitor has viewed can be included in query results. To exclude any item the visitor has viewed, use:

```html
$itemOptions.excludeViewedItems()
```

By default, Products that the visitor has purchased can be included in query results. To exclude any product the visitor has purchased, use:

```html
$itemOptions.excludePurchasedItems()
```

### Formatting Numbers

Typically, prices are the only numbers you need formatted. There are two options for how to format them.

#### Option 1

The simpler option formats the price with the default dataset currency symbol using the default dataset locale:

```html
$tools.formatPrice(${item.price})
```

If the default dataset currency is US dollars and the default dataset locale is US, the formatted currency would look like: `$1,234.50`

And for Euros with a French locale: `1 234,50 €`

#### Option 2

The other option is to format the number only using a fixed number of digits after the decimal point. Then, the currency symbol or word can be added as part of the message. For example:

```html
$tools.formatNumber(${item.price}, 0) ￥
```

Which would display as: `1,234 ￥`

## See Also

- [Advanced Dynamic Message Content Cheatsheet](https://developer.salesforce.com/docs/marketing/personalization/guide/advanced-dynamic-message-content-cheatsheet.md)
- _Salesforce Help_: [Dynamic Message Content](https://help.salesforce.com/s/articleView?id=sf.mc_pers_mobile_campaign_dynamic_message_content.htm)
- _Salesforce Help_: [Open Time Email Campaigns](https://help.salesforce.com/s/articleView?id=sf.mc_pers_email_campaign.htm)

<!-- document id=19467ecec22065991d9a55db53d0745783e0e132842286659be106849a935ec7 url=/developer/current/en-us/personalization/personalization/guides/additional-apis/user-export-api.md -->

# User Export API

Use the User Export API to export user data such as segments, engagement scores, changes in engagement scores, and user activity from Marketing Cloud Personalization datasets for use in other systems.

**note:** Your Personalization contract defines the volume of records you can export using the User Export API. For more information, refer to your contract or contact your account representative.

## Method and Endpoint

`GET` `/api/dataset/<datasetId>/users.< json | csv >`

## Request URL

`https://<accountName>.<instance>.evergage.com/api/dataset/<datasetId>/users.< json | csv >`

## Request Parameters

| URL Parameter    | Required? | Description                                                                                                                                                                                                                                            |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `accountName`    | **Yes**   | The Personalization account name. You can find the `accountName` by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the account name is `demo`.        |
| `instance`       | **Yes**   | The Personalization instance identifier. You can find this value by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the instance identifier is `us-1`. |
| `datasetId`      | **Yes**   | The name or identifier of the Personalization dataset you’re exporting user data from.                                                                                                                                                                 |
| `filter`         | No        | Optional Segment name or ID                                                                                                                                                                                                                            |
| `start`          | No        | Optional start time in epoch milliseconds used for engagement statistics                                                                                                                                                                               |
| `end`            | No        | Optional end time in epoch milliseconds used for engagement statistics                                                                                                                                                                                 |
| `segmentationId` | No        | Optional segmentation identifier                                                                                                                                                                                                                       |
| `segmentId`      | No        | Optional segment identifier                                                                                                                                                                                                                            |
| `pageSize`       | No        | Number of records to return. Returns all records unless specified.                                                                                                                                                                                     |
| `page`           | No        | Page number of records to show, starting at zero for the first page. Starts at zero unless specified.                                                                                                                                                  |
| `includeGeo`     | No        | Set as `true` to include user location details                                                                                                                                                                                                         |

## Authorization

`Authorization: Basic <base64-encoded-API-token>`

The User Export API uses API tokens to authenticate requests. Your API token must be a strict Base64 encoding of your API Key ID and its API Secret Key, separated by a colon. You can use an existing API token if it has the required permissions. Alternatively, you can ask an account administrator to generate a new one from the Personalization UI. For more information on API tokens, see [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm) on Salesforce Help.

Alternatively, if you use [cURL](https://curl.se/docs/manpage.html) to interact with the API, you can send your API Key ID and its API Key Secret using the `-u "apiKeyId:apiKeySecret"` command-line option. cURL automatically converts the `apiKeyId:apiKeySecret` pair into a Base64-encoded string and adds the `Authorization: Basic <base64-encoded-API-token>` to the request header. For an example of how to pass your API credentials in a cURL request, refer to the [Example](#example) section in this article.

## Example

The following is an example GET request sent using cURL that retrieves user data in the JSON format from the specified Personalization dataset.

**note:** The following example request passes API credentials using the `-u` command-line option.

```bash
curl -u "apiKeyId:apiKeySecret" \
     https://<accountName>.<instance>.evergage.com/api/dataset/<datasetId>/users.json
```

The preceding example cURL request generates this example response in the JSON format.

```json
[
  {
    "name": "john.doe@example.com",
    "engagementScore": 0.012,
    "engagementPercentChange": 0.002,
    "firstActivity": 1358957180647,
    "lastActivity": 1359066698647,
    "totalActions": 0,
    "attributes": {},
    "accountName": "Acme, Inc.",
    "displayName": "John Doe",
    "segments": []
  }
]
```

Here's an example in Node.js of how you can use the User Export API. In this example, the `fetchEvergageData()` function is called with the appropriate parameters to log user data from the specified Personalization dataset to the console.

```javascript
function fetchEvergageData(accountName, instance, datasetId, apiKeyId, apiKeySecret) {
  var authorizationString = btoa(apiKeyId + ":" + apiKeySecret);

  var options = {
    method: "GET",
    hostname: accountName + "." + instance + ".evergage.com",
    port: 443,
    path: "/api/dataset/" + datasetId + "/users.json",
    headers: {
      Authorization: "Basic " + authorizationString,
    },
  };

  var req = https.request(options, function (res) {
    var chunks = [];

    res.on("data", function (chunk) {
      chunks.push(chunk);
    });

    res.on("end", function (chunk) {
      var body = Buffer.concat(chunks);
      console.log(body.toString());
    });

    res.on("error", function (error) {
      console.error(error);
    });
  });

  req.end();
}
```

**note:** Exporting a large number of users can result in duplicate entries for the same user, especially if the user is updated just before or while the export is being processed. In such cases, the most current record for that user is always the last one in the export.

## See Also

- _Salesforce Help_: [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm)

<!-- document id=462c0a09f78d2e2df482d966f054c5d6d58bfad13627696cf09f18136661d4ae url=/developer/current/en-us/personalization/personalization/guides/web-integration/user-identity-mapping.md -->

# User Identity Mapping

The Marketing Cloud Personalization identity system helps map events sent from the Salesforce Interactions SDK to user records in Personalization. This article describes how events are mapped to user records in Personalization by the identity system and guidance on how to configure the identity system.

For additional information about how to configure identity types and attributes in the Personalization UI, see [Identity Management](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity.htm).

## Terms

The following table lists and describes terms used on this page and in the Identity System.

| Term               | Description                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User               | A record in Personalization that attempts to track and personalize for one individual.                                                                                                                                                                                                                                                                                                                      |
| Anonymous ID       | An identifier generated by the Web SDK that typically stays the same on a given device.                                                                                                                                                                                                                                                                                                                     |
| Named ID           | An identifier set in the integration by calling `setUser`. Before the Identity feature was released, only one type of named ID was allowed per integration and per user (except for the Eloqua/Salesforce sync). With the release of the Identity feature, you can provide one or more identity attributes in addition to calling `setUser`.                                                                |
| Primary User ID    | The internal identifier of the user record in Personalization that tracks the user's activity. Before the Identity feature was released, the primary user ID was always an anonymous ID or named ID called user ID.                                                                                                                                                                                         |
| Identity           | A new concept introduced by the Identity feature that connects an arbitrary number of identifiers of different types with each user by Primary User ID.                                                                                                                                                                                                                                                     |
| Identity Type      | The field used for identity matching; defined at the account level. Examples of identity types that you can create are email address and web user ID.                                                                                                                                                                                                                                                       |
| Identity Attribute | Any user attribute that is associated with an identity type; defined per dataset. These attributes can hold a user's identities. The attribute type must be string.                                                                                                                                                                                                                                         |
| Identity Namespace | An Identity Type uniqueness value that indicates that the identity attribute value is assigned to only one user in the dataset. The identity namespace is equivalent to the dataset.                                                                                                                                                                                                                        |
| Resolve User ID    | A command that requests the primary user ID associated with the set of identities.                                                                                                                                                                                                                                                                                                                          |
| Persisted User ID  | Traditionally, the Web SDK remembered the user ID from the previous request using an opaque token encrypted by the server. Instead, with the new Identity feature, the same encrypted token stores the primary user ID resolved by the server along with the set of identities (name and value) provided for the user in this visit. New identities are added/replaced as they are provided to the Web SDK. |

## Current Best Practice - Look Up Users Using Identity Attributes

As of September 2020, Personalization supports a more powerful way to map incoming events to users based on one or more identity attributes present in the event. To use this functionality, you must have the Pipeline Identity Resolution feature enabled for the tenant, and the identity system must be configured for the dataset as described in the help article [Configure the Identity System for the Web SDK](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity_web_sdk_configure.htm).

After you've configured a dataset to use identity attributes for user identity resolution, users are looked up purely by identity attributes rather than by primary ID, which Personalization automatically generates for new users as a unique, 24-character hexadecimal ID. Note that the primary ID is now system-managed and can no longer be used to look up users.

The new system is more powerful for a number of reasons. Whereas previously a known user could only be identified with one ID, now the user can still be identified by _any_ known identifier. For example, consider that you've configured a customer ID for the web identity attribute. If a user clicks a link in an email, the landing page URL could contain the user's email address or an ID assigned by the ESP. As long as they have been configured as identity attributes, the email address, or ESP ID could then be included in the event sent from the web to Personalization and used to look up an existing known user.

## The Traditional Approach - Look Up Users via Primary ID

**important:** he approach described in this section is no longer supported in the Personalization identity system. This section only describes the legacy approach to assist users from migrating away from directly manipulating `user.id`.

Traditionally, Personalization mapped incoming web events to a known user based on an event's `user.id` property. This ID represented the primary ID of the user entity stored by Personalization. On specifying `user.id` within a visit, the server would include the user ID in the `persistedUserId` property in the event response. The Web SDK would then automatically include this encrypted form of the ID in subsequent events in the same visit. When the `user.id` property was not yet known, the Web SDK would automatically include an `anonId` property in the event, which contained a 16-character unique hexadecimal anonymous ID generated by the Web SDK. On receiving an event with a set `user.id`, Personalization would temporarily use this anonymous ID as the user's primary ID and then automatically merge the user into a user with a named ID.

## Configuring the Identity System

The process for configuring the Personalization Identity System is detailed in the [Identity Types and Attributes](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity_type_attributes.htm) article on Salesforce Help and requires Personalization administrator permissions.

At a high level, you need to:

- **Review existing identity types**: Personalization has five pre-built identity types: email address, Salesforce CRM contact ID, Salesforce CRM lead ID, Salesforce Marketing Cloud contact key, and secondary email address.
- **Add any additional identity types**: Add any additional identity types to meet the needs of your business.
- **Configure attributes that correspond to identity types**: Even if you do not add additional identity types, you need to configure the attributes that correspond to the default identity types.

## Anonymous Users

In all events, the Web SDK includes a generated anonymous ID in the `user.anonymousId` property in the `SalesforceInteractions` namespace and the `user.anonId` property in the `Evergage` namespace. However, Personalization only considers the event anonymous and uses the anonymous ID as the user ID if the event does not include either `user.id` or any identity attributes are present in the event (remember `user.id` now represents the main web user ID, not the primary ID of the user in Personalization). If one or more identity attributes are present, Personalization uses them along with the main web user ID to look up an existing user. If not found, Personalization creates a user with a server-generated primary ID and does not use the anonymous ID from the event. As always, when an anonymous user logs in or is otherwise identified, Personalization automatically merges their activity into the identified user's profile.

**note:** Server-generated user IDs for identified users consist of 24 hexadecimal characters. On the other hand, Web-SDK-generated user IDs for anonymous users consist of 16 hexadecimal characters.

## Persisted User ID

The `persistedUserId` property in the event response is still essential in web identity tracking. Traditionally, the persisted user ID was simply the encrypted `user.id`. After the new identity resolution is enabled, it is still an encrypted string, but it is encoded in two parts instead:

- the server-resolved primary user ID
- the list of identity attribute name-value pairs that were used to resolve the primary user ID. This list is cumulative throughout a visit.

  For example, if page 1 sends `emailAddress=joe@example.com` and page 2 sends `loyaltyId=abc123`, Personalization uses both of these attributes to resolve the user and is encoded in the persisted user ID. As the Web SDK developer, you can include identity attributes in events as they are discovered; Personalization accumulates and remembers those IDs for the remainder of the visit. You do not need to track the set of discovered identity attributes.

Previously, the Personalization server would only include `persistedUsedId` in the response to the first event in a visit containing the `user.id` property. After identity resolution is enabled, the server will include the latest `persistedUserId` in every event response after the user is identified. The Web SDK automatically saves the most recently received `persistedUserId` in subsequent events, meaning that the Personalization server can reuse the resolved identity to avoid performing redundant identity resolutions. However, if an event contains a new identity attribute that is not already encoded in the persisted user ID, the server performs a new identity resolution that considers the new identity.

## Sending Identities Through the Sitemap

You can supply the default identity attribute you select as the Web SDK Identity as the `user.id` in web events configured in the Sitemap. In addition to the default identity, Personalization supports lookup and merges using the Web SDK for any other identity attributes supplied under `user.attributes` in web events. The set of all supplied identity attributes accumulates in the web browser. If there are changes to the default identity sent as `user.id`, Personalization clears the set of all identity attributes stored on the client. Changes to the default identity can happen when a different individual starts using the browser on the same device and logs in to a different account.

### Examples

#### Scenario 1: Only web user ID is known

`webUserIdentityTypeId` is set to `webId`. The user's web ID is known, so the Web SDK sends an event containing:

```javascript
{
    user: {
        anonymousId: '0123456789abcdef',
        id: 'abc123'
    }
}
```

```javascript
{
    user: {
        anonId: '0123456789abcdef',
        id: 'abc123'
    }
}
```

The Personalization server checks for an existing user with a `webId` identity attribute with value `abc123`. If found, the event activity is tracked against that user. If not, a new user is created with a generated primary ID, such as `8675309abacab5551212acdc`, and attribute `webId` with a value such as `abc123`. If there was any previous activity for the anonymous user with ID `0123456789abcdef`, that activity is merged into the identified user.

An alternate way to send the same information would be through the following event:

```javascript
{
    user: {
        anonymousId: '0123456789abcdef',
        identities: {
            webId: 'abc123'
        }
    }
}
```

```javascript
{
    user: {
        anonId: '0123456789abcdef',
        attributes: {
            webId: 'abc123'
        }
    }
}
```

#### Scenario 2: Only some other identity attribute is known

`webUserIdentityTypeId` is set to `webId`. The user's web ID is not known by the beacon, but the user's email address is known (a common scenario for an email clickthrough, or a non-logged-in user who signs up for an email list), so the Web SDK sends an event containing:

```javascript
{
    user: {
        anonymousId: '0123456789abcdef',
        identities: {
            emailAddress: 'billybob@example.com'
        }
    }
}
```

```javascript
{
    user: {
        anonId: '0123456789abcdef',
        attributes: {
            emailAddress: 'billybob@example.com'
        }
    }
}
```

The Personalization server checks if there is an existing user with a `emailAddress` identity attribute with value `billybob@example.com`. If found, the event activity is tracked against that user. If not, a new user is created with a generated primary ID, such as `8675309abacab5551212acdc`, and attribute `emailAddress` with value `billybob@example.com`. If there was any previous activity for the anonymous user with ID `0123456789abcdef`, that activity is merged into the identified user.

#### Scenario 3: Web user ID and another identity attribute are known but match two different users

`webUserIdentityTypeId` is set to `webId`. Both the user's web ID and email address are known, so the web SDK sends an event containing:

```javascript
{
    user: {
        anonymousId: '0123456789abcdef',
        id: 'abc123',
        identities: {
            emailAddress: 'billybob@example.com'
        }
    }
}
```

```javascript
{
    user: {
        anonId: '0123456789abcdef',
        id: 'abc123',
        attributes: {
            emailAddress: 'billybob@example.com'
        }
    }
}
```

The Personalization server checks for existing users with `webId` identity attribute with a value of `abc123` or `emailAddress` identity attribute with a value of `billybob@example.com`. Typically for a repeat visit, a single existing user is matched, but it is possible that two users could be matched - one user with `webId=abc123` and another user with `emailAddress=billybob@example.com`. When two users are matched, the Personalization server selects the user who was most recently active before this event. The activity from the other user is automatically merged into the selected user, and the other user is deleted from the system.

The resulting user record looks like:

```javascript
{
    id: '8675309abacab5551212acdc',
    identities: {
        webId: 'abc123',
        emailAddress: 'billybob@example.com'
    },
    <merged activity from both matched users>
}
```

```javascript
{
    id: '8675309abacab5551212acdc',
    attributes: {
        webId: 'abc123',
        emailAddress: 'billybob@example.com'
    },
    <merged activity from both matched users>
}
```

where `8675309abacab5551212acdc` is the ID of the user that was selected based on having more recent activity than the other user.

## See Also

- [_Salesforce Help_: Identity Management](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity.htm)
- [_Salesforce Help_: Configure the Identity System for the Web SDK](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity_web_sdk_configure.htm)

<!-- document id=dda3fa990c8d4c1b185b166fdb3d5d5ee5e20aead27e9a4b03104935a81af3df url=/developer/current/en-us/personalization/personalization/guides/additional-apis/user-look-up-deletion-api.md -->

# User Look-Up and Deletion API

The Marketing Cloud Personalization User Look-Up & Deletion API enables you to retrieve and delete user data on-demand to comply with data privacy regulations such as GDPR and CCPA. In addition to using the [Personalization UI](https://help.salesforce.com/s/articleView?id=sf.mc_pers_segment_user_bulk_delete.htm), you can use this API to service _Right of Access_ or _Right to be Forgotten_ requests that you receive from customers.

This API enables you to look up users by either primary user ID or anonymous ID. You can also use this API to delete users by either primary user ID, anonymous ID, or any other known identity attribute. Personalization processes deletion requests as soon as the requests are received. For more information on the Personalization Identity System, see [User Identity Mapping](https://developer.salesforce.com/docs/marketing/personalization/web-integration/user-identity-mapping.md).

The User Look-Up & Deletion API uses API tokens to authenticate all data change requests. An Account Administrator can generate API tokens from the Personalization UI. For more information on API tokens, see [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm&type=5) on Salesforce Help.

The following sections describe the various operations you can carry out using the API, and the associated endpoints.

---

## Export User by userId or anonId

Find and export a user in a Personalization dataset by `userId` (if named) or `anonId`.

### Method and Endpoint

- When using `userId`:

  `GET` `/api/dataset/{dataset}/user/{userId}`

- When using `anonId`:

  `GET` `/api/dataset/{dataset}/user/{anonId}`

### Request URL

- When using `userId`:

  ```bash
  https://<accountName>.<instance>.evergage.com/api/dataset/{dataset}/user/{userId}
  ```

- When using `anonId`:

  ```bash
  https://<accountName>.<instance>.evergage.com/api/dataset/{dataset}/user/{anonId}
  ```

### URL Parameters

| URL Parameter | Required?                                                              | Description                                                                                                                                                                                                                                            |
| ------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `accountName` | Yes                                                                    | The Personalization account name. You can find the `accountName` by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the account name is `demo`.        |
| `instance`    | Yes                                                                    | The Personalization instance identifier. You can find this value by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the instance identifier is `us-1`. |
| `dataset`     | Yes                                                                    | The name or identifier of the Personalization dataset you're looking up users from.                                                                                                                                                                    |
| `userId`      | Yes, if looking up named users.                                        | The user ID of the user you're looking up.                                                                                                                                                                                                             |
| `anonId`      | Yes, if looking up users with no known identity attribute or `userId`. | The anonymous ID of the user you're looking up.                                                                                                                                                                                                        |

### Response Content Type

`application/json`

### Response Example

```json
[
  {
    "name": "john.doe@example.com",
    "engagementScore": 0.012,
    "engagementPercentChange": 0.002,
    "firstActivity": 1358957180647,
    "lastActivity": 1359066698647,
    "totalActions": 0,
    "attributes": {},
    "accountName": "Acme, Inc.",
    "displayName": "John Doe",
    "segments": [],
    "location": {}
  }
]
```

## Remove a User from Personalization

Find and delete users from a Personalization dataset with user identifiers submitted via a CSV file. You can specify users to be deleted either by primary user IDs or any other single identity attribute. The CSV file you submit with the deletion request must specify the identity attribute to be used. If you don’t specify an identity attribute in the CSV file, the system assumes that the CSV file lists users by primary user IDs.

**important:** - A maximum of 30,000 users can be submitted for deletion per request.
- Deleting users via this API doesn’t opt out a user from future tracking. For more information on managing user consent and disabling tracking via the Personalization sitemap, refer to the [Consent Management](https://developer.salesforce.com/docs/marketing/personalization/web-integration.md) documentation.

### Method and Endpoint

`POST` `/api/dataset/{dataset}/users/delete`

### Request Content Type

`multipart/form-data`

### Request Example

The following code sample depicts an example CSV file that lists users to be looked up by the identity attribute `emailAddress` and deleted.

```bash
identityAttribute:emailAddress
tom@example.com
dick@example.com
harry@example.com
```

---

## Example - Deleting User Data with an API

The following section describes the steps to delete users, and their associated data with the Personalization API, along with example Bash and curl commands. You can modify and use these example commands to send in your own deletion requests via the User Look-Up & Deletion API.

1. Export your Personalization account name and instance identifier using Bash, as shown in the following example.

   ```bash
   export ACCOUNT='<accountName>.<instance>' # your account name and instance identifier
   ```

   **note:** You can find the values of `accountName` and `instance` by accessing **Gears** from the Personalization UI and reviewing the URL. For example, if the Gears URL is `https://demo.us-1.evergage.com/`, then the account name is `demo` and the instance identifier is `us-1.`

2. Export the `DATASET` your users belong to, as shown in the following example.

   ```bash
   export DATASET='dataset' # the name of your dataset
   ```

3. Export the API token to be used with the API request, as shown in the following example.

   ```bash
   export HTTP_BASIC_AUTH_STRING='<encoded-api-credential>' # Where <encoded-api-credential> is a strict Base64 encoding of your <api-key-id>:<api-secret-key>
   ```

   **note:** Your API token must be a strict Base64 encoding of your **API Key ID** and its **API Secret Key**. You can use an existing API token if it has the required permissions or generate a new one from the Personalization UI by navigating to **Security** > **API Tokens** > **Create Token**. For more information on API tokens, see [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens_create.htm) on Salesforce Help.

4. Export the CSV file to be submitted with your API request as a variable, as shown in the following example.

   ```bash
   export CSV_FILE='users.csv'
   ```

5. Write the identifiers of one or more users you'd like to delete to the CSV file, as shown in the following example.

   ```bash
   echo -e "name\ntom@example.com\ndick@example.com\nharry@example.com" > ${CSV_FILE}
   ```

6. Construct and send a curl request to delete users using the variables you declared in the previous steps, as shown in the following example.

   ```bash
   curl --form "file=@${CSV_FILE}" -H "Authorization: Basic ${HTTP_BASIC_AUTH_STRING}" "https://${ACCOUNT}.evergage.com/api/dataset/${DATASET}/users/delete"
   Deleted 3 users (3 requested)
   ```

7. Confirm whether your deletion request was processed by sending the same cURL request, as shown in the following example.

   ```bash
   curl --form "file=@${CSV_FILE}" -H "Authorization: Basic ${HTTP_BASIC_AUTH_STRING}" "https://${ACCOUNT}.evergage.com/api/dataset/${DATASET}/users/delete"
   Deleted 0 users (3 requested)
   ```

## See Also

- _Salesforce Help_: [Personalization API Tokens](https://help.salesforce.com/s/articleView?id=sf.mc_pers_api_tokens.htm)
- _Salesforce Help_: [Bulk Delete Users](https://help.salesforce.com/s/articleView?id=sf.mc_pers_segment_user_bulk_delete.htm)

<!-- document id=879ef022478eb9bc506609263b5bca1aca625e43803d10e86bfeb808a9da87fc url=/developer/current/en-us/personalization/personalization/guides/web-integration/validate-javascript-beacon-deployment.md -->

# Validate JavaScript Beacon Deployment

Marketing Cloud Personalization supports web channel campaigns by integrating with websites using a [JavaScript web beacon](https://developer.salesforce.com/docs/marketing/personalization/web-integration.md#web-sdk-javascript-beacon) that provides access to the Personalization module of the [Salesforce Interactions SDK](https://developer.salesforce.com/docs/marketing/personalization/web-integration.md#interaction-studio-web-sdk). Website pages that do not contain the beacon do not have behavioral tracking or personalization capabilities. This article describes steps you can take to validate the [JavaScript beacon's](https://developer.salesforce.com/docs/marketing/personalization/web-integration.md)) presence on the desired website pages.

**note:** - A configured [Sitemap](https://developer.salesforce.com/docs/marketing/personalization/guide/personalization-sitemap.md) is **not** required to validate the JavaScript beacon deployment.
- Personalization does not support multiple beacons on a page.

---

## Beacon Deployment Validation Steps

1. Check the integration type intended for your Personalization web integration. For guidance on Personalization integration types, see [Plan a Web Integration](https://developer.salesforce.com/docs/marketing/personalization/guide/web-integration-planning.md) and [Synchronous or Asynchronous Integration](https://developer.salesforce.com/docs/marketing/personalization/guide/web-integration-considerations.md#synchronous-or-asynchronous-integration).
2. Confirm that the JavaScript beacon script tag is present in the HTML of the desired website pages. If the JavaScript beacon is present, the website's HTML contains `script` tags as shown in the following example.

   - Synchronous

     ```html
     <script
       type="text/javascript"
       src="//cdn.evgnet.com/beacon/myaccount/mydataset/scripts/evergage.min.js"
     ></script>
     ```

   - Asynchronous

     ```html
     <script type="text/javascript">
       var _aaq = window._aaq || (window._aaq = []);

       (function () {
         var d = document,
           g = d.createElement("script"),
           s = d.getElementsByTagName("script")[0];
         g.type = "text/javascript";
         g.async = true;
         g.src =
           document.location.protocol +
           "//cdn.evgnet.com/beacon/myaccount/mydataset/scripts/evergage.min.js";
         s.parentNode.insertBefore(g, s);
       })();
     </script>
     ```

3. Open the Chrome DevTools **Console** panel and ensure that the `window.SalesforceInteractions` object is defined. If you're using the `Evergage` SDK namespace, ensure that the `window.Evergage` object is defined.

<!-- document id=da1eb6d56a666e73b9b0b40d3107cbdc6c83c463821b31ba2e6e141923c254aa url=/developer/current/en-us/personalization/personalization/guides/campaign-development/web-campaigns-templates.md -->

# Web Campaigns and Templates

As you work to modify existing templates or build out your custom template, referencing code in the global templates is often a great place to start. Even if they do not map precisely to the use case you are building, the global templates provide template developers with a view into common functions/configurations that can help you solve your use cases. The following table provides a quick breakdown of some of the key code components used in our global templates.

| **Global Template**                          | **Key Code Components Leveraged in the Template**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | **Sample Configuration Options to Consider**                                                                                                                   |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Banner with Call-To-Action                   | <ul><li>[Decorators](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/decorators.md)</li> <li>[Select Property](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/properties/select.md)</li> <li>[Flicker Defender](https://developer.salesforce.com/docs/marketing/personalization/guide/web-campaigns-templates/flicker-defender.md)</li> <li>[Campaign Stats Gear](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/campaign-stats-tracking.md)</li></ul>                                                                                                                                                                                                                                                                                                                        | <ul><li>Number of calls to action (CTAs)</li> <li>Text/CTA location</li> <li> Banner size</li><li>Banner style (flat image vs. layered)</li></ul>              |
| Einstein Content Recommendations             | <ul><li>[Decorators](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/decorators.md)</li> <li>[Recommendations API](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-template-apis/recommendations.md)</li> <li>[Flicker Defender](https://developer.salesforce.com/docs/marketing/personalization/guide/web-campaigns-templates/flicker-defender.md)</li> <li>[Campaign Stats Gear](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/campaign-stats-tracking.md)</li></ul>                                                                                                                                                                                                                                                                                                                                          | <ul><li>Number of recommended items (content)</li> <li>Style of recommendations</li> <li>Location of recommendations based on mapped content zones </li></ul>  |
| Einstein Decisions - Server-Side Template    | <ul><li>[Corvus](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-template-apis/corvus-ai.md)</li> <li>[Flicker Defender](https://developer.salesforce.com/docs/marketing/personalization/guide/web-campaigns-templates/flicker-defender.md)</li> <li>[Campaign Stats Gear](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/campaign-stats-tracking.md)</li> <li>Lifecycle Component</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                | <ul><li>Number of recommended items (content)</li> <li>Location of recommendations based on mapped content zones </li></ul>                                    |
| Einstein Product Recommendations             | <ul><li>[Decorators](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/decorators.md)</li> <li>[Recommendations API](https://developer.salesforce.com/docs/marketing/personalization/guide/campaign-template-apis/recommendations.md)</li> <li>[Flicker Defender](https://developer.salesforce.com/docs/marketing/personalization/guide/web-campaigns-templates/flicker-defender.md)</li> <li>[Campaign Stats Gear](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/campaign-stats-tracking.md)</li></ul>                                                                                                                                                                                                                                                                                                                                          | <ul><li>Number of recommended items (products)</li> <li>Style of recommendations</li> <li>Location of recommendations based on mapped content zones </li></ul> |
| Exit Intent                                  | <ul><li>[Decorators](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/decorators.md)</li> <li>[Select Property](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/properties/select.md)</li> <li>[Rich Text (String Property)](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/properties/string.md)</li> <li>[Display Utils (Client-Side Code)](https://developer.salesforce.com/docs/marketing/personalization/guide/web-campaigns-templates/web-template-display-utilities.md)</li> <li>[Flicker Defender](https://developer.salesforce.com/docs/marketing/personalization/guide/web-campaigns-templates/flicker-defender.md)</li> <li>[Campaign Stats Gear](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/campaign-stats-tracking.md)</li></ul>                                                                                                         | <ul><li>Number of CTAs</li> <li>Text/CTA location</li> <li>Pop-up image style (flat or layered)</li> <li>Pop-up contents (recipe inclusion)</li></ul>          |
| Exit Intent with Email Capture               | <ul><li>[Decorators](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/decorators.md)</li> <li>[Select Property](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/properties/select.md)</li> <li>[Display Utils (Client-Side Code)](https://developer.salesforce.com/docs/marketing/personalization/guide/web-campaigns-templates/web-template-display-utilities.md)</li> <li>[Flicker Defender](https://developer.salesforce.com/docs/marketing/personalization/guide/web-campaigns-templates/flicker-defender.md)</li> <li>[Evg.sendEvent (send value entered in campaign to user attribute) client-side code](https://developer.salesforce.com/docs/marketing/personalization/web-integration/capturing-user-account-attributes.md#setting-user-and-account-attributes-using-event-listeners)</li> <li>[Campaign Stats Gear](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/campaign-stats-tracking.md)</li></ul> | <ul><li>Text/CTA location</li> <li>Pop-up image style (flat or layered)</li> <li>Attribute collected</li> </ul>                                                |
| Google Analytics Segment Push                | <ul><li>[Decorators](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/decorators.md)</li> <li>User Segment Reference / Lookup from the Common Gear</li> </ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | <ul><li>Limited default options due to specificity of template</li></ul>                                                                                       |
| Infobar with User Attribute & Call-To-Action | <ul><li>[Decorators](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/decorators.md)</li> <li>[Select Property](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/properties/select.md)</li> <li>Illustrates how to render a user attribute in a campaign response (Server-Side Code)</li> <li>[Flicker Defender](https://developer.salesforce.com/docs/marketing/personalization/guide/web-campaigns-templates/flicker-defender.md)</li> <li>[Campaign Stats Gear](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/campaign-stats-tracking.md)</li></ul>                                                                                                                                                                                                                          | <ul><li>Number of CTAs</li> <li>User attribute leveraged (default is visitor's name)</li> <li>Text and background color/styles</li></ul>                       |
| Infobar with Call-To-Action                  | <ul><li>[Decorators](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/decorators.md)</li> <li>[Select Property](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/properties/select.md)</li> <li>[Flicker Defender](https://developer.salesforce.com/docs/marketing/personalization/guide/web-campaigns-templates/flicker-defender.md)</li> <li>[Campaign Stats Gear](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/campaign-stats-tracking.md)</li></ul>                                                                                                                                                                                                                                                                                                                        | <ul><li>Number of CTAs</li> <li>Infobar styling</li> </ul>                                                                                                     |
| Redirect                                     | <ul><li>[Decorators](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/decorators.md)</li> <li>[Evergage.sendStat](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/campaign-stats-tracking.md#sending-campaign-stats-without-the-campaign-stats-gear)</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                                              |
| Slide-In with Call-To-Action                 | <ul><li>[Decorators](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/decorators.md)</li> <li>[Select Property](https://developer.salesforce.com/docs/marketing/personalization/custom-interface-template-configuration/properties/select.md)</li> <li>[Display Utils (Client-Side Code)](https://developer.salesforce.com/docs/marketing/personalization/guide/web-campaigns-templates/web-template-display-utilities.md)</li> <li>[Flicker Defender](https://developer.salesforce.com/docs/marketing/personalization/guide/web-campaigns-templates/flicker-defender.md)</li> <li>[Campaign Stats Gear](https://developer.salesforce.com/docs/marketing/personalization/guide/templates/campaign-stats-tracking.md)</li></ul>                                                                                                                                                                                                                 | <ul><li>Number of CTAs</li> <li>Text and background color/styles</li> <li>Slide-in location & speed</li></ul>                                                  |

<!-- document id=79825bcec15631664091fddd0e799c710338c60f6e187c49d17ff139d94b8f76 url=/developer/current/en-us/personalization/personalization/guides/web-integration/web-integration-considerations.md -->

# Web Integration Considerations

Before integrating the JavaScript beacon for the Marketing Cloud Personalization module of the Salesforce Interactions SDK, you must consider the following.

- Whether to integrate the JavaScript beacon synchronously or asynchronously
- Whether to self-host the JavaScript beacon or host it on the Personalization CDN

## Synchronous or Asynchronous Integration

Page flicker is a momentary flash of the original page content. Depending on how you'd like to deal with page flicker, there are two methods to choose from when integrating the JavaScript beacon for the Salesforce Interactions SDK - synchronous or asynchronous.

Synchronous integration loads the Personalization JavaScript beacon before loading the rest of the page. This integration method allows Personalization to prevent page flicker.

Asynchronous integration loads the JavaScript beacon after loading the page. With this integration method, Personalization can’t prevent page flicker.

### Comparison of Synchronous and Asynchronous Approaches

To select the best integration method for your organization, talk to your business users about their requirements and desired use cases. The following table outlines some common pros and cons of each approach.

|         | Synchronous                                                                                                                                                                                                                                                                                                                                                                                          | Asynchronous                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Summary | The Salesforce Interactions SDK loads completely before page content loads. This method of deployment is highly recommended for the best user experience. For a synchronous integration, Salesforce recommends deploying the JavaScript beacon in the header of the website.                                                                                                                         | The Salesforce Interactions SDK begins to load at the point it appears in the HTML for the page. Page contents continue to load while the SDK loads.                                                                                                                                                                                                                                                                                                                                      |
| Pros    | <ul> <li> Personalization can track data and deploy personalized campaigns as soon as possible within the browser page lifecycle. </li> <li> This method is compatible with ZeroFlicker, which prevents content from popping into view and then flickering as personalized content replaces the default content on the page. Instead, the first visible content is already personalized. </li> </ul> | Typically, you can use a tag manager, such as Google Tag Manager, for this integration.                                                                                                                                                                                                                                                                                                                                                                                                   |
| Cons    | This method delays page rendering by the amount of time required to load the Salesforce Interactions SDK on the first viewed page and every two minutes thereafter. You can minimize the impact by: <ul><li>Reducing the data size of the Salesforce Interactions SDK </li><li>Delivering using a global content delivery network (CDN)</li><li>Using client-side caching</li></ul>                  | <ul><li> This method can potentially present a poor user experience due to page flicker. Flicker occurs when content appears on the page and then rapidly changes after the initial page loads as the SDK personalizes the page content.</li><li>This method can delay tracking and personalization. Depending on the site and complexity of the page and other loaded libraries, this delay can increase, which can cause missed page tracking as users navigate away quickly.</li></ul> |

## Considerations for Self-Hosting the JavaScript Beacon

For web integrations using the Marketing Cloud Personalization module of the Salesforce Interactions SDK, the Personalization content delivery network (CDN) hosts the JavaScript beacon. However, your organization can assume the responsibility of self-hosting the JavaScript beacon, if necessary.

The following table lists considerations for self-hosting the JavaScript beacon in web integrations for Personalization.

| Consideration                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Disabling the JavaScript beacon | When you self-host the JavaScript beacon, you can’t use the toggle in Personalization to disable it. The toggle only functions when the Personalization CDN hosts the JavaScript beacon. If you want to disable the JavaScript beacon, your development team must do so.                                                                                                                                                                            |
| JavaScript beacon monitoring    | When the Personalization CDN doesn’t host the JavaScript beacon, Personalization can't monitor whether events are being tracked and campaigns are being served correctly. When self-hosting the JavaScript beacon, you assume responsibility for monitoring and maintaining the hosting CDN to ensure that data is flowing as expected.                                                                                                             |
| JavaScript beacon refreshes     | When you self-host the JavaScript beacon and update or edit your sitemap, you must refresh the JavaScript beacon to ensure the updates apply. Similarly, if you enable or disable a Personalization gear, you must refresh the JavaScript beacon.                                                                                                                                                                                                   |
| JavaScript beacon updates       | Periodic updates or enhancements that Salesforce releases for the JavaScript beacon aren’t automatically applied to self-hosted JavaScript beacons. When self-hosting the JavaScript beacon, you assume responsibility for monitoring the Personalization CDN URL on a regular basis to ensure your JavaScript beacon version is up to date. If a new version is available, you’re responsible for updating the version you’re hosting on your CDN. |

<!-- document id=6bd598efd5268b2dee0eacbb1b7f7fc40eff02f43957c18aa9b5715ca9a77252 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/advanced-use-case-apis/web-surveys.md -->

# Web Surveys

Marketing Cloud Personalization Surveys uses [SurveyJS](https://surveyjs.io/) to build and render surveys on your website. Surveys are deployed within web campaigns, leveraging Personalization's targeting rules and testing capabilities.

Use survey data to create user segments, enhance personalization experiences, A/B test to validate business impact, and analyze feedback. You can clone or build a survey using the Surveys editor in the Personalization UI, or use the SurveyJS JSON editor for more advanced customization. For more information about Personalization Surveys, see [Surveys](https://help.salesforce.com/s/articleView?id=mktg.mc_pers_survey_about.htm). For detailed documentation on using the JSON survey editor, see the official [SurveyJS documentation](https://surveyjs.io/form-library/documentation/overview).

## Before You Begin

- Surveys are available to all Premium edition customers. If your account was created before April 7, 2021, request a Gears refresh from Support to turn on this feature. Your account administrator can then review the Gears list to confirm whether the Surveys Gear is enabled.
- Create at least one survey in the Surveys editor within the Personalization UI.

With these steps complete, you're ready to use Surveys in your web campaign templates.

To learn how to create a survey, see [Create a Survey](https://help.salesforce.com/s/articleView?id=sf.mc_pers_survey_create.htm).

## Third-Party Library

[SurveyJS](https://surveyjs.io/)

- Version: 1.0.95
- Sizes:
  - JS (compressed) - 149 KB
  - CSS (compressed) - 4 KB

This version of SurveyJS is a variant of the jQuery version, updated to use the [Cash](https://kenwheeler.github.io/cash/#docs) library included in the Personalization module of the Salesforce Interactions SDK. However, features such as SurveyJS custom widgets are currently not supported.

## API

### Methods

This code injects the SurveyJS library, renders the survey, and handles responses upon completion.

```typescript
renderSurvey(survey: Survey, renderTarget: Element): Promise<void>
```

The `Survey` interface defines the structure of the survey object, containing its ID, name, and the SurveyJS JSON configuration.

```typescript
interface Survey {
  id: string;
  name: string;
  config: SurveyConfig; // references SurveyJS's JSON object
}
```

To integrate custom resources, such as themes, use `injectSurveyResourcesIntoPage()`.

```typescript
injectSurveyResourcesIntoPage(): Promise<void>
```

### Implementation

1. Invoking `renderSurvey` automatically injects the SurveyJS library from the Personalization CDN using `injectSurveyResourcesIntoPage` on page load.

   **note:** This automatic injection doesn't occur for client-side page changes, such as those within a [Single-Page Application (SPA)](https://developer.mozilla.org/en-US/docs/Glossary/SPA).

2. The survey renders after the SurveyJS library instance loads.
3. Upon completion or submission of each survey page, the system parses the survey configuration and sends an event with each user's responses stored as survey attributes.

## Store Responses on the User Profile

Survey attributes are automatically created when you design a survey. You can view them in Personalization under **Settings > Attributes > Survey Attributes**. These attributes populate an individual user's profile with their survey responses only after Personalization receives a survey event in the correct format. For information about sending a survey event, see [Send a Survey Event](#send-a-survey-event).

Upon receiving a survey event, Personalization stores the responses within corresponding survey attributes. Each event must include the `surveyId`, `surveyStartTime`, and all survey attributes representing the user's responses.

Depending on the type of question, survey responses are stored in these formats:

- Matrix questions: `survey:<surveyId>:<questionId>:<rowId>`
- Other question types: `survey:<surveyId>:<questionId>`

Personalization generates `<surveyId>` and `<questionId>` to identify surveys and questions respectively. `<rowId>` is a unigue ID for a row within a Matrix question and is omitted for other question types.

By default, Personalization limits the number of survey attributes to 10.

### Send a Survey Event

The Surveys Gear automatically handles survey submissions and sends survey events in the required format. As a developer, you don't need to include any code that sends a survey event within your web campaign template.

These examples show how to manually track a survey event in each SDK namespace, if needed.

**important:** Avoid tracking survey events outside the Surveys gear.

```javascript
SalesforceInteractions.sendEvent({
    source: {
        surveyId: "string"
        surveyStartTime: "string"
    },
    user: {
        attributes: {
            "survey:<surveyId>:<questionId>:<rowId>": "string"
        }
    }
})
```

```javascript
Evergage.sendEvent({
    source: {
        surveyId: "string"
        surveyStartTime: "string"
    },
    user: {
        attributes: {
            "survey:<surveyId>:<questionId>:<rowId>": "string"
        }
    }
})
```

## Style Surveys

You can style your surveys in different ways using methods described in the SurveyJS documentation. Some of these methods include using [Custom CSS](https://surveyjs.io/Examples/Library/?id=survey-customcss&platform=jQuery&theme=bootstrap#content-js) and creating a [Custom Theme](https://surveyjs.io/Examples/Library/?id=custom-theme&platform=jQuery&theme=bootstrap#content-js).

These examples demonstrate how to apply custom styling with client-side JavaScript using the `applyTheme` function.

```javascript
function apply(context, template) {
  const contentZoneSelector = SalesforceInteractions.mcis.getContentZoneSelector(
    context.contentZone,
  );

  return SalesforceInteractions.DisplayUtils.bind(buildBindId(context))
    .pageElementLoaded(contentZoneSelector)
    .then((element) => {
      const $survey = SalesforceInteractions.cashDom(template(context).trim());

      return SalesforceInteractions.mcis.Surveys.injectSurveyResourcesIntoPage().then(() => {
        Survey.StylesManager.applyTheme("default");
        return SalesforceInteractions.mcis.Surveys.renderSurvey(context.survey, $survey).then(
          () => {
            SalesforceInteractions.cashDom(element).append($survey);
          },
        );
      });
    });
}
```

```javascript
function apply(context, template) {
  const contentZoneSelector = Evergage.getContentZoneSelector(context.contentZone);

  return Evergage.DisplayUtils.bind(buildBindId(context))
    .pageElementLoaded(contentZoneSelector)
    .then((element) => {
      const $survey = Evergage.cashDom(template(context).trim());

      return Evergage.Surveys.injectSurveyResourcesIntoPage().then(() => {
        Survey.StylesManager.applyTheme("default");
        return Evergage.Surveys.renderSurvey(context.survey, $survey).then(() => {
          Evergage.cashDom(element).append($survey);
        });
      });
    });
}
```

## Track Survey Statistics

When using the sample survey template in this section in a web campaign, an impression statistic is automatically tracked after the initial page of the survey renders. To track additional statistics, see [Campaign Stats Tracking](https://developer.salesforce.com/docs/marketing/personalization/templates/campaign-stats-tracking.md).

**Handlebars code**

```handlebars
{{!--
    Template: Sample Survey Template

    Requirements:
    1) Surveys are available to all Premium edition customers. If your account was provisioned prior to 4/7/2021, you
        will need to request a gears refresh for your account from support in order for the Survey gear to show up in
        your gears list and for the feature functionality to be fully enabled.
    2) Create at least one Survey in the Survey editor, which can be found in the Personalization UI.
--}}

<div id="evg-surveys" data-evg-campaign-id="{{campaign}}" data-evg-experience-id="{{experience}}"
    data-evg-user-group="{{userGroup}}" aria-label="Survey{{#if survey}} - {{survey.name}}{{/if}}">
</div>
```

**CSS**

```css
/* Default Theme */
```

**Client-side JavaScript**

```javascript
(function () {
  /**
    * @function buildBindId
    * @param {Object} context
    * @description Create unique bind ID based on the campaign and experience IDs.
    */
  function buildBindId(context) {
    return `${context.campaign}:${context.experience}`;
  }

  function apply(context, template) {
    const contentZoneSelector = SalesforceInteractions.mcis.getContentZoneSelector(
      context.contentZone,
    );

    return SalesforceInteractions.DisplayUtils.bind(buildBindId(context))
      .pageElementLoaded(contentZoneSelector)
      .then((element) => {
        const $survey = SalesforceInteractions.cashDom(template(context).trim());

        return SalesforceInteractions.mcis.Surveys.renderSurvey(context.survey, $survey).then(
          () => {
            SalesforceInteractions.cashDom(element).append($survey);
          },
        );
      });
  }

  function reset(context, template) {
    SalesforceInteractions.DisplayUtils.unbind(buildBindId(context));
    SalesforceInteractions.cashDom(
      `[data-evg-campaign-id="${context.campaign}"][data-evg-experience-id="${context.experience}"]`,
    ).remove();
  }

  function control(context) {
    const contentZoneSelector = SalesforceInteractions.mcis.getContentZoneSelector(
      context.contentZone,
    );
    return SalesforceInteractions.DisplayUtils.bind(buildBindId(context))
      .pageElementLoaded(contentZoneSelector)
      .then((element) => {
        SalesforceInteractions.cashDom(element).attr({
          "data-evg-campaign-id": context.campaign,
          "data-evg-experience-id": context.experience,
          "data-evg-user-group": context.userGroup,
        });
      });
  }

  registerTemplate({
    apply: apply,
    reset: reset,
    control: control,
  });
})();
```

```javascript
(function () {
  /**
    * @function buildBindId
    * @param {Object} context
    * @description Create unique bind ID based on the campaign and experience IDs.
    */
  function buildBindId(context) {
    return `${context.campaign}:${context.experience}`;
  }

  function apply(context, template) {
    const contentZoneSelector = Evergage.getContentZoneSelector(context.contentZone);

    return Evergage.DisplayUtils.bind(buildBindId(context))
      .pageElementLoaded(contentZoneSelector)
      .then((element) => {
        const $survey = Evergage.cashDom(template(context).trim());

        return Evergage.Surveys.renderSurvey(context.survey, $survey).then(() => {
          Evergage.cashDom(element).append($survey);
        });
      });
  }

  function reset(context, template) {
    Evergage.DisplayUtils.unbind(buildBindId(context));
    Evergage.cashDom(
      `[data-evg-campaign-id="${context.campaign}"][data-evg-experience-id="${context.experience}"]`,
    ).remove();
  }

  function control(context) {
    const contentZoneSelector = Evergage.getContentZoneSelector(context.contentZone);
    return Evergage.DisplayUtils.bind(buildBindId(context))
      .pageElementLoaded(contentZoneSelector)
      .then((element) => {
        Evergage.cashDom(element).attr({
          "data-evg-campaign-id": context.campaign,
          "data-evg-experience-id": context.experience,
          "data-evg-user-group": context.userGroup,
        });
      });
  }

  registerTemplate({
    apply: apply,
    reset: reset,
    control: control,
  });
})();
```

**Server-side TypeScript**

```typescript
import { SurveyReference, SurveyReferenceLookup } from "surveys";

export class SurveyTemplate implements CampaignTemplateComponent {
  @title("Survey Selector")
  @lookupOptions(() => new SurveyReferenceLookup())
  surveyReference: SurveyReference;

  run(context: CampaignComponentContext) {
    const survey = context.services.surveys.getSurvey(this.surveyReference.id);
    return {
      survey: survey,
    };
  }
}
```

## Sample Template

Download the sample survey template for your SDK namespace:

- [`SalesforceInteractions` namespace](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/SampleSurveyTemplate-SalesforceInteractions.zip)
- [`Evergage` namespace](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/SampleSurveyTemplate-Evergage.zip)

## See Also

- [_Salesforce Help_: Create a Survey](https://help.salesforce.com/s/articleView?id=sf.mc_pers_survey_create.htm)
- [_External Link_: SurveyJS](https://surveyjs.io/)
- [_External Link_: Cash Documentation](https://github.com/fabiospampinato/cash#documentation)

<!-- document id=f6ebb9425efda8bbb9be3593376e52634693bac4a576f35273f06e64ec548ddb url=/developer/current/en-us/personalization/personalization/guides/campaign-development/web-campaigns-templates/web-template-building-best-practices.md -->

# Web Template Building Best Practices

This article outlines best practices for building templates that run optimally on your website.

## Campaign Stats Tracking

If you would like to track campaign stats with Marketing Cloud Personalization, use the data attributes (`data-evg-*`) in the Handlebars HTML. Note that using these data attributes requires the Campaign Stat Tracking gear installed and enabled for your dataset.

Visit the [Campaign Stats Tracking](https://developer.salesforce.com/docs/marketing/personalization/templates/campaign-stats-tracking.md) article to learn more.

## Deferred Rendering

Depending on the SDK namespace you're using, use `SalesforceInteractions.DisplayUtils.pageElementLoaded` or `Evergage.DisplayUtils.pageElementLoaded` to defer rendering of your template until the content zone or target element has loaded on the webpage. Note that this method requires the Display Utilities gear installed and enabled for your dataset.

Visit the [Template Display Utilities](https://developer.salesforce.com/docs/marketing/personalization/guide/web-template-display-utilities.md) article to learn more.

## Zero Flicker Compatibility

In order to prevent "flicker" (where the original website content appears briefly before being replaced by the template), the `apply` function in the Client-side Code must return a Promise that resolves when the template renders. Note that the Flicker Defender gear must also be installed and enabled for your dataset.

Visit the [Flicker Defender](https://developer.salesforce.com/docs/marketing/personalization/guide/flicker-defender.md) article to learn more.

## Accessibility Standards

Develop templates with accessibility in mind. To provide access to individuals who use assistive technologies like screen readers, ensure that your template is compliant with Web Content Accessibility Guidelines (WCAG).

Visit the [Templates Style Guide and Coding Conventions](https://developer.salesforce.com/docs/marketing/personalization/guide/web-templates-style-guide-and-coding-conventions.md) article to learn more. Read the two sections on "Accessibility" under "Handlebars HTML" and "CSS".

## Cross-browser Compatibility

Develop your template to be compatible across different browsers as needed. Click the "Test" button in the template editor to test your template on your website in a new separate browser window.

<!-- document id=709293cc1b3123d04ff63a1e740d74cf4c3966cb22a257b6d49f792310492939 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/web-campaigns-templates/web-template-display-utilities.md -->

# Web Template Display Utilities

DisplayUtils is a versatile set of utility functions primarily designed to support Single Page Applications (SPAs). However, these functions are not limited to SPAs and can be utilized on any type of webpage. DisplayUtils offers various APIs that enable tracking of page behavior, including detecting page exit intention, monitoring page inactivity, tracking page scroll, observing visible and loaded elements, and more.

The following code sample showcases the methods available in DisplayUtils.

```typescript
type UnbindFunction = () => any;

interface Bindings {
  [id: string]: UnbindFunction;
}

interface BaseMethods {
  pageElementVisible(selector: string, percentage: number): Promise<IntersectionObserverEntry>;
  pageExit(delay?: number): Promise<Event>;
  pageInactive(ms: number): Promise<Event>;
  pageScroll(percentage: number): Promise<Event>;
  pageElementLoaded(targetSelector: string, observerSelector?: string): Promise<Element>;
}

interface BindingMethods {
  bind(id: string): BaseMethods;
  unbind(id): void;
  getBindings(): Bindings;
  clearBindings(): void;
}
```

---

## Binding Elements to `BaseMethods`

With DisplayUtils, you can use the `bind` function to link elements to `BaseMethods` using a specified ID, allowing for convenient removal of associated listeners or observers with the same ID in the future.

```typescript
bind(id: string): BaseMethods
```

- If the `bind()` function is used alone, it generates IDs based on function name and selector.
- If no `bind()` function is used, it generates a random ID.
- When rebinding with the same ID, the previous binding gets unbound, and the new unbind method gets set to the ID.

Here are some examples of how to use the `bind()` function in the `SalesforceInterections` and `Evergage` SDK namespaces.

```
// Examples:
// binded id is "id"
SalesforceInteractions.DisplayUtils.bind("id")
  .pageElementVisible("selector")
  .then(function (entry) {
    console.log("At least 1px of target in view.");
  });
// binded id is "<pageElementVisible>selector"
SalesforceInteractions.DisplayUtils.bind()
  .pageElementVisible("selector")
  .then(function (entry) {
    console.log("At least 1px of target in view.");
  });
// binded id is "nmelsbd6pq"(random)
SalesforceInteractions.DisplayUtils.pageElementVisible("selector").then(function (entry) {
  console.log("At least 1px of target in view.");
});
```

```
// Examples:
// binded id is "id"
Evergage.DisplayUtils.bind("id")
  .pageElementVisible("selector")
  .then(function (entry) {
    console.log("At least 1px of target in view.");
  });
// binded id is "<pageElementVisible>selector"
Evergage.DisplayUtils.bind()
  .pageElementVisible("selector")
  .then(function (entry) {
    console.log("At least 1px of target in view.");
  });
// binded id is "nmelsbd6pq"(random)
Evergage.DisplayUtils.pageElementVisible("selector").then(function (entry) {
  console.log("At least 1px of target in view.");
});
```

---

## Unbinding Elements

The `unbind()` function enables you to cancel listeners or observers associated with the specified ID.

```typescript
unbind(id): void
```

To remove all associated listeners or observers, call the `unbind()` function with the same ID that was used when binding the element to `BaseMethods`. Here are some examples of how to use the `unbind()` function in the `SalesforceInteractions`and`Evergage` SDK namespaces.

```
// Examples:
SalesforceInteractions.DisplayUtils.unbind("id");
```

```
// Examples:
Evergage.DisplayUtils.unbind("id");
```

---

## Retrieving Element Bindings

The `getBindings()` function enables you to retrieve all the bind IDs and their associated unbinding functions.

```typescript
getBindings(): Bindings
```

Here are some examples of how to use the `getBindings()` function in the `SalesforceInteractions` and `Evergage` SDK namespaces.

```
// Examples:
SalesforceInteractions.DisplayUtils.getBindings();
```

```
// Examples:
Evergage.DisplayUtils.getBindings();
```

---

## Removing Element Bindings

The `clearBindings()` function enables you to remove all known bindings by iterating through each known binding and unbinding them all.

```typescript
clearBindings(): void
```

Here are some examples of how to use the `clearBindings()` function in the `SalesforceInteractions` and `Evergage` SDK namespaces.

```
// Examples:
SalesforceInteractions.DisplayUtils.clearBindings();
```

```
// Examples:
Evergage.DisplayUtils.clearBindings();
```

---

## Determining Visibility of Page Elements

```typescript
pageElementVisible(selector: String, percentage: Number): Promise
```

The `pageElementVisible` function checks whether a page element specified by the CSS `selector` is visible in the viewport. When the specified element is visible, it returns a `Promise` that resolves with an `entry` object that contains data about the visible element.

By default, the `pageElementVisible` function triggers the resolve function when at least 1 pixel of the target element is visible. You can also specify a `percentage` of the target element that must be visible in the viewport for the resolve function to be triggered. The `pageElementVisible` function only triggers the resolve function one time.

The function throws an error with the message "**[pageElementVisible] Invalid arguments**" when:

- `selector` isn’t a string
- `percentage` isn’t a number
- `percentage` is less than zero
- `percentage` is greater than one

Here are some examples of how to use the `pageElementVisible` function in the `SalesforceInteractions` and `Evergage` SDK namespaces.

```
// Examples:
SalesforceInteractions.DisplayUtils.pageElementVisible("selector").then(function (entry) {
  console.log("At least 1px of target in view.");
});
SalesforceInteractions.DisplayUtils.pageElementVisible("selector", 0.5).then(function (entry) {
  console.log("At least 50% of target in view.");
});
```

```
// Examples:
Evergage.DisplayUtils.pageElementVisible("selector").then(function (entry) {
  console.log("At least 1px of target in view.");
});
Evergage.DisplayUtils.pageElementVisible("selector", 0.5).then(function (entry) {
  console.log("At least 50% of target in view.");
});
```

---

## Detecting Page Exit Intent

```typescript
pageExit(delay?: Number): Promise
```

The `pageExit` function enables you to detect a user's page exit intent by tracking when the cursor leaves the bounds of the body from the top of the page. Upon detection, this function triggers a resolve function with or without a specified delay. The `pageExit` function only triggers the resolve function one time.

This function accepts a `delay` parameter that you can use to specify the delay, in milliseconds, before the resolve function is triggered. The default value is o, which also means there’s no delay specified.

The `pageExit` function listens for the `mousemove` event to detect when the cursor leaves the bounds of the body from the top of the page. If it detects more mouse movement in the body within the delay period after leaving the window, it clears the exit intent detection delay, but doesn't remove the event listed.

**important:** Although Personalization web templates support displaying web campaigns on mobile devices, the `pageExit` function doesn't detect exit intent on mobile devices as it relies on listening for mouse move events on a page.

The function throws an error with the message "**[pageExit] Invalid arguments**" when:

- `delay` isn’t a number
- `delay` is less than 0

Here are some examples of how to use the `pageExit` function in the `SalesforceInteractions` and `Evergage` SDK namespaces.

```
// Examples:
SalesforceInteractions.DisplayUtils.pageExit(2000).then(function (event) {
  console.log("Exit Intent Detected - 2 second delay");
});

SalesforceInteractions.DisplayUtils.pageExit().then(function (event) {
  console.log("Exit Intent Detected - no delay");
});
```

```
// Examples:
Evergage.DisplayUtils.pageExit(2000).then(function (event) {
  console.log("Exit Intent Detected - 2 second delay");
});

Evergage.DisplayUtils.pageExit().then(function (event) {
  console.log("Exit Intent Detected - no delay");
});
```

---

## Detecting Page Inactivity

```typescript
pageInactive(ms: Number): Promise
```

The `pageInactive` function enables you to detect user inactivity on a page by triggering a resolve function after a specified period without any user activity. You can specify the time period in milliseconds using the `ms` parameter.

This function listens for `mousemove`, `click`, `scroll`, `keyup`, and `keydown` events. The detection of any of these events resets the inactivity timer and prevents the resolve function from triggering.

You can use the `pageInactive` function with either of the following methods:

- The `.then` method, which only triggers the resolve function one time
- The `.subscribe` method, which continues to trigger the resolve function upon detecting inactivity until the `event.disconnect` function is called.

The `event` parameter returns the last event that triggered the inactivity timer and can be of type `mousemove`, `click`, `scroll`, `keyup`, or `keydown`.

The function throws an error with the message "**[pageInactive] Invalid arguments**" when:

- `ms` isn’t a number
- `ms` is less than 0

Here are some examples of how to use the `pageInactive` function in the `SalesforceInteractions` and `Evergage` SDK namespaces.

```
// Examples:
var count = 0;
SalesforceInteractions.DisplayUtils.pageInactive(1000).subscribe(function (event) {
  if (count >= 3) {
    return event.disconnect();
  }
  console.log("inactive for 1 second");
  count++;
});

SalesforceInteractions.DisplayUtils.pageInactive(2000).then(function (event) {
  console.log("inactive for 2 seconds");
});
```

```
// Examples:
var count = 0;
Evergage.DisplayUtils.pageInactive(1000).subscribe(function (event) {
  if (count >= 3) {
    return event.disconnect();
  }
  console.log("inactive for 1 second");
  count++;
});

Evergage.DisplayUtils.pageInactive(2000).then(function (event) {
  console.log("inactive for 2 seconds");
});
```

---

## Tracking Page Scrolling

```typescript
pageScroll(percentage: Number): Promise
```

The `pageScroll` function enables you to trigger a resolve function when a user scrolls past a specified percentage of a page. You must specify the `percentage` parameter as a decimal value from 0 through 1. This function only triggers the resolve function one time.

**note:** Since the `pageScroll` function doesn’t detect the direction of scrolling, it triggers either when scrolling from top to bottom or bottom to top.

The `event` parameter returns the scroll event when a user scrolls past the specified percentage.

**important:** Be mindful when using the `pageScroll` function on pages with dynamic heights, as it can affect the percentage calculation.

The function throws an error with the message "**[pageScroll] Invalid arguments**" when:

- `percentage` isn’t a number
- `percentage` is less than 0
- `percentage` is greater than 1

Here are some examples of how to use the `pageScroll` function in the `SalesforceInteractions` and `Evergage` SDK namespaces.

```
// Examples:
SalesforceInteractions.DisplayUtils.pageScroll(0.5).then(function (event) {
  console.log("PageScroll has passed 50%");
});
```

```
// Examples:
Evergage.DisplayUtils.pageScroll(0.5).then(function (event) {
  console.log("PageScroll has passed 50%");
});
```

---

## Watching Page Elements Load

```typescript
pageElementLoaded(targetSelector: string, observerSelector?: string): Promise
```

The `pageElementLoaded` function triggers a resolve function when a target element loads on a page. This function triggers a resolve function only one time. The `element` parameter of the resolve function returns the target element that was loaded.

The `pageElementLoaded` function accepts the following two arguments:

- `targetSelector`: A string that specifies the target element to be watched. The `targetSelector` must be a non-empty string.
- `observerSelector` (optional): A string that specifies the element to watch for mutations. The `observerSelector` must be a non-empty string. If no `observerSelector` is specified, the `pageElementLoaded` function binds a listener to the `body` or `html` element and waits for the `targetSelector` to be added as a descendant.

**important:** Be mindful when using `observerSelector` as it can cause performance issues. Ensure that the `observerSelector` configured in the `pageElementLoaded` function is available on the page when running a campaign.

The `pageElementLoaded` function throws an error with the message "**[pageElementLoaded] Invalid arguments**" if the following conditions aren't met:

- `targetSelector` must be a non-empty string
- `observerSelector` (if specified) must be a non-empty string

**tip:** You can use a [Mutation Observer](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) to watch for added nodes.

Here are examples of using the `pageElementLoaded` function in the `SalesforceInteractions` and `Evergage` SDK namespaces.

```
// Examples:
setTimeout(function () {
  SalesforceInteractions.cashDom("body div").append("<div class='evg-element'></div>");
}, 1000);

SalesforceInteractions.DisplayUtils.pageElementLoaded(".evg-element").then(function (
  element,
) {
  console.log("Element is loaded | then");
});

SalesforceInteractions.DisplayUtils.pageElementLoaded(".evg-element", "body div").then(
  function (element) {
    console.log("Element is loaded | delegate");
  },
);
```

```
// Examples:
setTimeout(function () {
  Evergage.cashDom("body div").append("<div class='evg-element'></div>");
}, 1000);

Evergage.DisplayUtils.pageElementLoaded(".evg-element").then(function (element) {
  console.log("Element is loaded | then");
});

Evergage.DisplayUtils.pageElementLoaded(".evg-element", "body div").then(function (element) {
  console.log("Element is loaded | delegate");
});
```

<!-- document id=445d95fcb6b7f280829a9df123b6feadadfb6e12bc00fefcfec192aff313bf70 url=/developer/current/en-us/personalization/personalization/guides/campaign-development/templates/web-template-handlebars.md -->

# Web Template Handlebars

With the Handlebars Templates Gear enabled, HTML received with a web campaign is rendered using [Handlebars](https://handlebarsjs.com/guide/#what-is-handlebars) templated HTML.

**note:** The preceding link to the external **Handlebars** site is for information purposes only. Some of the code structures and functions of the Handlebars templating language are incorporated as part of the Personalization module of the Salesforce Interactions SDK when the Handlebars Templates Gear is installed and enabled. The Handlebars Templates Gear is installed with Marketing Cloud Personalization and enabled by default, but a Personalization administrator can disable or enable this Gear.

## Handlebars Templated HTML

Handlebars is a simple HTML templating language that uses a template and an input object to generate HTML. A Handlebars expression is an opening double-brace `{{`, some contents, followed by a closing double-brace `}}`. The following is an example of a simple Handlebars expression.

```handlebars
<p>{{firstname}} {{lastname}}</p>
```

In creating templates, developers enter Handlebars template code in the template editor's **Handlebars** tab. On executing a Handlebars template within a Personalization web template, each Handlebars expression is replaced with values from the specified input object. In Personalization web templates, the template variables in the Handlebars expressions are populated by the [Web Template Context](https://developer.salesforce.com/docs/marketing/personalization/web-campaigns-templates.md#web-template-context) provided by the [Client JavaScript](https://developer.salesforce.com/docs/marketing/personalization/guide/template-client-javascript.md) objects specified in the **Clientside Code** tab.

## See Also

- _Salesforce Developers_: [Content Security Policies and Personalization JavaScript Beacon Directives](https://developer.salesforce.com/docs/marketing/web-integration/content-security-policies-javascript-beacon-directives.md)
- _External Link_: [Handlebars JS](https://handlebarsjs.com/guide/#what-is-handlebars)

<!-- document id=21ab1373c90259e85fe6d2c163f8ed68f5f39d363323eaf9463b9d29f51069fe url=/developer/current/en-us/personalization/personalization/guides/campaign-development/templates/web-template-css.md -->

# Web Template HTML Classes and CSS

Marketing Cloud Personalization web templates support any valid [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) styling for the target browsers of your website. It is good practice to prefix all classes with `evg-` so they do not conflict with styling already on your website.

This article lists suggested HTML class names prefixed with `evg-`, descriptions of their intended purposes, and examples of CSS styling. If you need more classes than the ones listed here, refer to [Bootstrap classes](https://getbootstrap.com/docs/4.5/getting-started/introduction/) for ideas.

## HTML Classes and CSS Styles

The following is a list of suggested HTML class names categorized by the website elements they target.

- [Web Template HTML Classes and CSS](#web-template-html-classes-and-css)
  - [HTML Classes and CSS Styles](#html-classes-and-css-styles)
    - [Jumbotron Classes](#jumbotron-classes)
      - [.evg-jumbotron](#evg-jumbotron)
      - [.evg-cta](#evg-cta)
    - [Product Recommendation Classes](#product-recommendation-classes)
      - [.evg-product-recommendations](#evg-product-recommendations)
      - [.evg-product-recommendation](#evg-product-recommendation)
      - [.evg-product-image](#evg-product-image)
      - [.evg-product-details](#evg-product-details)
      - [.evg-product-name](#evg-product-name)
      - [.evg-product-description](#evg-product-description)
      - [.evg-product-price](#evg-product-price)
      - [.evg-product-rating](#evg-product-rating)
      - [.evg-star-empty](#evg-star-empty)
      - [.evg-star-fill](#evg-star-fill)
    - [Content Recommendation Classes](#content-recommendation-classes)
      - [.evg-content-recommendations](#evg-content-recommendations)
      - [.evg-content-recommendation](#evg-content-recommendation)
      - [.evg-content-image](#evg-content-image)
      - [.evg-content-details](#evg-content-details)
      - [.evg-content-title](#evg-content-title)
      - [.evg-content-description](#evg-content-description)
    - [Form Classes](#form-classes)
      - [.evg-form](#evg-form)
      - [.evg-error-msg](#evg-error-msg)
      - [.evg-opt-out-msg](#evg-opt-out-msg)
      - [.evg-email](#evg-email)
    - [Modal Classes](#modal-classes)
      - [.evg-modal](#evg-modal)
      - [.evg-overlay](#evg-overlay)
    - [Popup Classes](#popup-classes)
      - [.evg-popup](#evg-popup)
      - [.evg-cta](#evg-cta-1)
      - [.evg-overlay](#evg-overlay-1)
      - [.evg-main-panel](#evg-main-panel)
      - [.evg-confirm-panel](#evg-confirm-panel)
    - [Button Classes](#button-classes)
      - [.evg-btn](#evg-btn)
      - [.evg-btn-primary](#evg-btn-primary)
      - [.evg-btn-secondary](#evg-btn-secondary)
      - [.evg-btn-outline-primary](#evg-btn-outline-primary)
      - [.evg-btn-outline-secondary](#evg-btn-outline-secondary)
      - [.evg-btn-sm](#evg-btn-sm)
      - [.evg-btn-lg](#evg-btn-lg)
      - [.evg-btn-dismissal](#evg-btn-dismissal)
    - [Heading Classes](#heading-classes)
      - [.evg-header](#evg-header)
      - [.evg-subheader](#evg-subheader)
      - [.evg-h1](#evg-h1)
      - [.evg-h2](#evg-h2)
      - [.evg-h3](#evg-h3)
      - [.evg-h4](#evg-h4)
      - [.evg-h5](#evg-h5)
      - [.evg-h6](#evg-h6)
    - [Display Classes](#display-classes)
      - [.evg-display-1](#evg-display-1)
      - [.evg-display-2](#evg-display-2)
      - [.evg-display-3](#evg-display-3)
      - [.evg-display-4](#evg-display-4)
    - [Typography Classes](#typography-classes)
      - [.evg-text-primary](#evg-text-primary)
      - [.evg-text-secondary](#evg-text-secondary)
      - [.evg-text-sm](#evg-text-sm)
      - [.evg-text-lg](#evg-text-lg)
      - [.evg-dark-on-light](#evg-dark-on-light)
      - [.evg-light-on-dark](#evg-light-on-dark)
      - [.evg-link](#evg-link)
    - [Other Classes](#other-classes)
      - [.evg-hide](#evg-hide)

### Jumbotron Classes

#### .evg-jumbotron

The parent container class of a jumbotron-style hero banner.

```css
.evg-jumbotron {
  position: relative;
  z-index: 2;
  display: -webkit-flex;
  display: flex;
  -webkit-flex-flow: column nowrap;
  flex-flow: column nowrap;
  -webkit-justify-content: center;
  justify-content: center;
  -webkit-align-items: center;
  align-items: center;
  width: 100%;
  height: 500px;
  padding: 10px;
  background-size: cover;
}
```

#### .evg-cta

Applies styling for call-to-action buttons.

```css
.evg-cta {
  display: inline-block;
  vertical-align: middle;
  margin-left: 0.5rem;
  font-size: 1rem;
  color: #fff;
  background-color: #000;
}
```

### Product Recommendation Classes

#### .evg-product-recommendations

The parent container class of a product recommendations block. Applies styling for the layout of all product recommendations.

```css
.evg-product-recommendations {
  position: relative;
  z-index: 2;
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-box-orient: horizontal;
  -webkit-box-direction: normal;
  -ms-flex-flow: row nowrap;
  flex-flow: row nowrap;
  -webkit-box-pack: space-between;
  -ms-flex-pack: space-between;
  justify-content: space-between;
  -webkit-box-align: stretch;
  -ms-flex-align: stretch;
  align-items: stretch;
  width: auto;
  height: 100%;
  padding: 0;
}
```

#### .evg-product-recommendation

The container class of a single product recommendation. Applies styling for the layout of the content within each product recommendation.

```css
.evg-product-recommendation {
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-box-orient: vertical;
  -webkit-box-direction: normal;
  -ms-flex-flow: column nowrap;
  flex-flow: column nowrap;
  -webkit-box-pack: center;
  -ms-flex-pack: center;
  justify-content: center;
  -webkit-box-align: end;
  -ms-flex-align: end;
  align-items: flex-end;
  width: auto;
  margin: 0;
  padding: 0 0.5rem;
  text-align: center;
}
```

#### .evg-product-image

Applies styling for the product image for each product recommendation.

```css
.evg-product-image {
  width: 80%;
  height: auto;
}
```

#### .evg-product-details

Applies styling for the body of each product recommendation.

```css
.evg-product-details {
  width: 100%;
  height: 100%;
  min-height: 9rem;
  padding: 0.5rem 0;
}
```

#### .evg-product-name

Applies styling for the product name of each product recommendation.

```css
.evg-product-name {
  display: block;
  max-width: 90%;
  min-height: 2.5rem;
  margin: auto auto 0.25rem;
  color: #393939;
  font-size: 1rem;
  font-weight: 600;
  line-height: 1.25rem;
  text-decoration: none;
}
```

#### .evg-product-description

Applies styling for the product description of each product recommendation.

```css
.evg-product-description {
  overflow: hidden;
  width: 95%;
  max-height: 2rem;
  margin: 0 auto;
  font-size: 0.85rem;
  line-height: 1rem;
}
```

#### .evg-product-price

Applies styling for the product price of each product recommendation.

```css
.evg-product-price {
  margin-bottom: 0.5rem;
}
```

#### .evg-product-rating

Applies styling for the product rating of each product recommendation.

```css
.evg-product-rating {
  width: 5rem;
  margin: 0 auto 0.5rem auto;
  text-align: left;
  text-decoration: none;
}
```

#### .evg-star-empty

Applies styling for the empty rating stars of each product recommendation.

```css
.evg-star-empty {
  color: #dee3e8;
  background-color: #ffffff;
  text-align: left;
  text-decoration: none;
}
```

#### .evg-star-fill

Applies styling for filled rating stars of each product recommendation.

```css
.evg-star-fill {
  position: relative;
  overflow: hidden;
  margin-top: -1.4em;
  color: #ce763c;
  background-color: transparent;
}
```

### Content Recommendation Classes

#### .evg-content-recommendations

The parent container class of a content recommendations block. Applies styling for the layout of all content recommendations.

```css
.evg-content-recommendations {
  position: relative;
  z-index: 2;
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-box-orient: horizontal;
  -webkit-box-direction: normal;
  -ms-flex-flow: row wrap;
  flex-flow: row wrap;
  -webkit-box-pack: center;
  -ms-flex-pack: center;
  justify-content: center;
  -webkit-box-align: start;
  -ms-flex-align: start;
  align-items: flex-start;
  width: auto;
  max-width: 960px;
  margin: 0 auto;
}
```

#### .evg-content-recommendation

The container class of a single content recommendation.

```css
.evg-content-recommendation {
  margin: 1.5rem;
}
```

#### .evg-content-image

Applies styling for the content image of each content recommendation.

```css
.evg-content-image {
  display: block;
  width: 100%;
  height: auto;
  margin: 0;
}
```

#### .evg-content-details

Applies styling for the body of each content recommendation.

```css
.evg-content-details {
  overflow: hidden;
  width: 100%;
  padding: 1rem;
  background-color: #fff;
  text-align: left;
}
```

#### .evg-content-title

Applies styling for the content title of each content recommendation.

```css
.evg-content-title {
  overflow: hidden;
  height: 2.5rem;
  margin: 0 auto 0.75rem auto;
  font-size: 1.5rem;
  font-weight: 600;
  line-height: 2.5rem;
  text-decoration: none;
}
```

#### .evg-content-description

Applies styling for the content description of each content recommendation.

```css
.evg-content-description {
  overflow: hidden;
  height: 8rem;
  font-size: 1.25rem;
  line-height: 2rem;
}
```

### Form Classes

#### .evg-form

The parent container class of a form.

```css
.evg-form {
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;

  -webkit-box-orient: vertical;
  -webkit-box-direction: normal;
  -ms-flex-direction: column;
  flex-direction: column;

  -webkit-box-pack: center;
  -ms-flex-pack: center;
  justify-content: center;

  -webkit-box-align: center;
  -ms-flex-align: center;
  align-items: center;

  width: 100%;
  text-align: center;
}
```

#### .evg-error-msg

Applies styling for error message texts.

```css
.evg-error-msg {
  color: #ff0000;
  font-size: 1rem;
}
```

#### .evg-opt-out-msg

Applies styling for an opt-out message.

```css
.evg-opt-out-msg {
  font-size: 1rem;
  text-decoration: underline;
  cursor: pointer;
}
```

#### .evg-email

Applies styling for an email input field.

```css
.evg-email {
  width: 75%;
  margin: 0.5rem 0;
  padding: 0.5rem 1rem;
  border: 1px solid #ddd;
  color: #59575c;
}
```

### Modal Classes

#### .evg-modal

The parent container class of a window.

```css
.evg-modal {
  position: relative;
  z-index: 10000000;
}
```

#### .evg-overlay

Applies a semi-transparent layer over the page, behind a popup or a window.

```css
.evg-overlay {
  position: fixed;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  opacity: 0.3;
  width: 100%;
  height: 100%;
  background-color: #000;
}
```

### Popup Classes

#### .evg-popup

The parent container class of a popup.

```css
.evg-popup {
  position: fixed;
  top: 50%;
  left: 50%;
  width: 500px;
  height: 500px;
  padding: 20px;
  background-color: #fff;
  background-position: center bottom;
  background-size: cover;
  background-repeat: no-repeat;
  transform: translateX(-50%) translateY(-50%);
}
```

#### .evg-cta

Applies styling for call-to-action buttons.

```css
.evg-cta {
  display: inline-block;
  vertical-align: middle;
  margin-left: 0.5rem;
  font-size: 1rem;
  color: #fff;
  background-color: #000;
}
```

#### .evg-overlay

Applies a semi-transparent layer over the page, behind a popup or a window.

```css
.evg-overlay {
  position: fixed;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  opacity: 0.3;
  width: 100%;
  height: 100%;
  background-color: #000;
}
```

#### .evg-main-panel

The container class of the main panel of a popup. Applies styling for the layout of the content within the panel.

```css
.evg-main-panel {
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-box-orient: vertical;
  -webkit-box-direction: normal;
  -ms-flex-direction: column;
  flex-direction: column;
  -webkit-box-pack: center;
  -ms-flex-pack: center;
  justify-content: center;
  -webkit-box-align: center;
  -ms-flex-align: center;
  align-items: center;
  width: 100%;
  height: 100%;
  text-align: center;
}
```

#### .evg-confirm-panel

The container class of the secondary confirmation panel of a popup. Applies styling for the layout of the content within the panel.

```css
.evg-confirm-panel {
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-box-orient: vertical;
  -webkit-box-direction: normal;
  -ms-flex-direction: column;
  flex-direction: column;
  -webkit-box-pack: center;
  -ms-flex-pack: center;
  justify-content: center;
  -webkit-box-align: center;
  -ms-flex-align: center;
  align-items: center;
  width: 100%;
  height: 100%;
  text-align: center;
}
```

### Button Classes

#### .evg-btn

Applies basic styling to the button, including spacing and sizing. Use class on button, anchor, or input elements.

```css
.evg-btn {
  display: inline-block;
  vertical-align: middle;
  padding: 0.5rem 1rem;
  border: 1px solid transparent;
  border-radius: 3rem;
  color: #215ca0;
  background-color: transparent;
  font-size: 1rem;
  font-weight: 400;
  line-height: 1.5;
  text-align: center;
  text-decoration: none;
  cursor: pointer;
  transition: color 0.15s ease-in-out, background-color 0.15s ease-in-out,
    border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out;
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
}
```

#### .evg-btn-primary

Applies a solid primary color background to the button, adding more visual weight.

```css
.evg-btn-primary {
  color: #ffffff;
  border-color: #215ca0;
  background-color: #215ca0;
  transition: background-color 0.15s, color 0.15s;
}

.evg-btn-primary:hover {
  color: #ffffff;
  border-color: #1c4e88;
  background-color: #1c4e88;
}
```

#### .evg-btn-secondary

Applies a solid secondary color background to the button, adding more visual weight.

```css
.evg-btn-secondary {
  color: #ffffff;
  border-color: #6c757d;
  background-color: #6c757d;
  transition: background-color 0.15s, color 0.15s;
}

.evg-btn-secondary:hover {
  color: #ffffff;
  border-color: #59595c;
  background-color: #59595c;
}
```

#### .evg-btn-outline-primary

Removes the background color on any button (transparent) and colors the text and border using the primary color.

```css
.evg-btn-outline-primary {
  color: #215ca0;
  border-color: #215ca0;
  transition: background-color 0.15s, color 0.15s;
}

.evg-btn-outline-primary:hover {
  color: #ffffff;
  border-color: #215ca0;
  background-color: #215ca0;
}
```

#### .evg-btn-outline-secondary

Removes the background color on any button (transparent) and colors the text and border using the secondary color.

```css
.evg-btn-outline-secondary {
  color: #6c757d;
  border-color: #6c757d;
  transition: background-color 0.15s, color 0.15s;
}

.evg-btn-outline-secondary:hover {
  color: #ffffff;
  border-color: #6c757d;
  background-color: #6c757d;
}
```

#### .evg-btn-sm

Decreases the default button size.

```css
.evg-btn-sm {
  padding: 0.25rem 0.75rem;
  font-size: 0.875rem;
}
```

#### .evg-btn-lg

Increases the default button size.

```css
.evg-btn-lg {
  padding: 0.5rem 2rem;
  font-size: 1.25rem;
}
```

#### .evg-btn-dismissal

Styles the button into an "X" symbol. Whenever possible, use this class on a `button` element with an `aria-label="Close"`.

```css
.evg-btn-dismissal {
  position: absolute;
  top: 0;
  right: 0;
  padding: 0 0.5rem;
  border: 1px solid transparent;
  background-color: transparent;
  font-size: 2rem;
  font-weight: 700;
  line-height: 1;
  cursor: pointer;
}
```

### Heading Classes

#### .evg-header

Applies unique styling for headers.

```css
.evg-header {
    display: block;
    max-width: 90%;
    height: fit-content;
    text-align: center;
    margin-bottom: .5rem;
    font-size: 1.75rem;
    line-height: 1.75rem;
```

#### .evg-subheader

Applies unique styling for subheaders.

```css
.evg-subheader {
    display: block;
    max-width: 90%;
    height: fit-content;
    text-align: center;
    margin-bottom: .5rem;
    font-size: 1.5rem;
    font-weight: 300;
    line-height: 1.5rem;
```

#### .evg-h1

Applies styling for a level 1 heading.

```css
.evg-h1 {
  font-size: 2.5rem;
}
```

#### .evg-h2

Applies styling for a level 2 heading.

```css
.evg-h2 {
  font-size: 2rem;
}
```

#### .evg-h3

Applies styling for a level 3 heading.

```css
.evg-h3 {
  font-size: 1.75rem;
}
```

#### .evg-h4

Applies styling for a level 4 heading.

```css
.evg-h4 {
  font-size: 1.5rem;
}
```

#### .evg-h5

Applies styling for a level 5 heading.

```css
.evg-h5 {
  font-size: 1.25rem;
}
```

#### .evg-h6

Applies styling for a level 6 heading.

```css
.evg-h6 {
  font-size: 1rem;
}
```

**note:** Use `role="heading" aria-level="<heading level number>"` if you use non-semantic tags like a `div` to ensure that the headings are accessible.

### Display Classes

Classes for headers outside of the main page content, like jumbotron display headers. Use these classes to increase the font size of headings.

#### .evg-display-1

Increases size of the heading to the largest level.

```css
.evg-display-1 {
  font-size: 6rem;
  font-weight: 700;
  line-height: 1.2;
}
```

#### .evg-display-2

Increases size of the heading to the second largest level.

```css
.evg-display-2 {
  font-size: 5.5rem;
  font-weight: 700;
  line-height: 1.2;
}
```

#### .evg-display-3

Increases size of the heading to the third largest level.

```css
.evg-display-3 {
  font-size: 4.5rem;
  font-weight: 700;
  line-height: 1.2;
}
```

#### .evg-display-4

Increases size of the heading to the fourth largest level.

```css
.evg-display-4 {
  font-size: 3.5rem;
  font-weight: 700;
  line-height: 1.2;
}
```

### Typography Classes

#### .evg-text-primary

Changes text color to the primary color.

```css
.evg-text-primary {
  color: #343a40;
}
```

#### .evg-text-secondary

Changes text color to the secondary color.

```css
.evg-text-secondary {
  color: #6c757d;
}
```

#### .evg-text-sm

Decreases size of text within the main content (non-heading) of the page.

```css
.evg-text-sm {
  font-size: 0.85rem;
}
```

#### .evg-text-lg

Increases size of text within the main content (non-heading) of the page.

```css
.evg-text-lg {
  font-size: 1.25rem;
}
```

#### .evg-dark-on-light

Applies a dark text over light background color theme. Use to change the text color in the foreground and the color of the background.

```css
.evg-element1.evg-dark-on-light {
  color: #343a40;
}
.evg-element2.evg-dark-on-light {
  background-color: #fff;
}
```

#### .evg-light-on-dark

Applies a light text over dark background color theme. Use to change the text color in the foreground and the color of the background

```css
.evg-element1.evg-light-on-dark {
  color: #fff;
}
.evg-element2.evg-light-on-dark {
  background-color: #343a40;
}
```

#### .evg-link

Applies styling for text links.

```css
.evg-element1.evg-light-on-dark {
  color: #fff;
}
.evg-element2.evg-light-on-dark {
  background-color: #343a40;
}
```

### Other Classes

#### .evg-hide

Class for hiding elements.

```css
.evg-hide {
  visibility: hidden;
  display: none;
  width: 0;
  height: 0;
}
```

## See Also

- [_External Link_: Bootstrap](https://getbootstrap.com/docs/4.5/getting-started/introduction/)

<!-- document id=a340714c5e04784f9dc9c2b46bbaf95e1d88d741c5190b39efb0c1256bbb077f url=/developer/current/en-us/personalization/personalization/guides/campaign-development/web-campaigns-templates/web-templates-style-guide-and-coding-conventions.md -->

# Web Templates Style Guide and Coding Conventions

This document shares best practices that Marketing Cloud Personalization template developers follow for writing consistent HTML (Handlebars), CSS, and JavaScript code. Use this documentation as a guide for developing your own templates.

## Handlebars HTML

### HTML Syntax

- Indent nested elements 4 spaces (one press of the TAB key in the template editor).
- Break long lines to improve readability, up to 120 characters maximum per line. Place HTML attributes that extend beyond 120 characters on a new continuation line, indented 4 spaces.
- Use double quotes ( `""` ) instead of single quotes ( `''` ) for HTML attributes, as shown in the following example.

  ```html
  <a class="evg-cta evg-btn evg-btn-primary evg-btn-lg" href="/sale"></a>
  ```

- Contain all the handlebars HTML content within a single element.
- Write all code in lowercase, including HTML element names, attributes, and attribute values.
- Use HTML elements for their designed purpose. Whenever possible, use [semantic elements](https://developer.mozilla.org/en-US/docs/Glossary/Semantics#semantics_in_html) that describe the meaning of the content. See the section on "Accessibility" for more details.

### ID and Class Nomenclature

- Add an ID attribute to the outermost element, using a name specific to the template being built, and prefix with the `evg-` namespace (for example, `id=“evg-hero-banner”`). Use an ID for only this outermost HTML element and do not use the same ID in more than one template.
- Use classes for all other nested elements. Prefix classes with the `evg-` namespace (for example, `class=“evg-btn”`).
- Use hyphens to separate words in class and id names.

```html
<div id="evg-sale-banner">
  <h1 class="evg-header evg-h1">One Day Sale!</h1>
  <a class="evg-cta evg-btn evg-btn-primary" href="/sale">SHOP</a>
</div>
```

### Template HTML Classes

For suggested `evg-` prefixed class names and descriptions of their intended purpose, as well as examples of CSS styling, refer to [Template HTML Classes and CSS](https://developer.salesforce.com/docs/marketing/personalization/templates/web-template-css.md).

### Attributes Order

List your HTML attributes in the following order to improve readability.

1. `class`
2. `id`, `name`
3. `data-*`, `data-evg-*`
4. `src`, `for`, `type`, `href`, `value`
5. `title`, `alt`
6. `role`, `aria-*`
7. `style`

### Campaign Stats Tracking

If you would like to track campaign stats with Personalization, use the data attributes (`data-evg-*`) available in the Handlebars HTML. These data attributes require that the Campaign Stat Tracking gear is installed and enabled for your dataset.

Example:

```html
<div
  id="evg-new-template"
  data-evg-campaign-id="{{campaign}}"
  data-evg-experience-id="{{experience}}"
  data-evg-user-group="{{userGroup}}"
>
  ...
</div>
```

See the [Campaign Stats](https://developer.salesforce.com/docs/marketing/personalization/templates/campaign-stats-tracking.md) article on this site to learn more.

### Comments

For comments you wish to keep in the Handlebars-generated HTML output, use the native HTML comment format:

```html
<!-- This comment will show up as a HTML comment -->

<!--
    This comment will also
    show up as a HTML comment
-->
```

For comments you wish to remove in the resulting HTML output, use the following Handlebars HTML comment format.

```handlebars
{{! Single-line comments go here. This comment will not appear in the HTML output}}

{{!
    Multi-line comments go here.
    This comment will not appear in the HTML output.
}}
```

Any Handlebars HTML comment that includes double curly braces or Handlebars expressions must adhere to the following format. These comments also _do not_ appear in the resulting HTML output:

```handlebars
{{!-- This comment can contain }}, {{, or {{ ... }} --}}

{{!--
    Multi-line comments go here.
    This comment will not appear in the HTML output.
    {{ handlebars expression }}
--}}
```

For more information, see the [Handlebars documentation](https://handlebarsjs.com/guide/#template-comments) on template comments.

## CSS

### CSS Syntax

- Place the leading brace on the same line as the selector.

  ```
/* bad */
  #evg-banner .evg-cta
  {
    color: red;
  }

  /* good */
  #evg-banner .evg-cta {
    color: red;
  }
```

- Add one space between the colon and value of each property. No space before the colon.

  ```
/* bad */
  #evg-banner .evg-cta {
    color:red;
  }

  /* bad */
  #evg-banner .evg-cta {
    color :red;
  }

  /* good */
  #evg-banner .evg-cta {
    color: red;
  }
```

- For each declaration, indent 4 spaces (one press of the TAB key in the template editor) and include a single space after the colon. End each declaration with a semicolon ( `;` ). Add a blank line between rulesets.
- Add one space before the leading brace.

  ```
/* bad */
  #evg-banner .evg-cta{
    color: red;
  }

  /* good */
  #evg-banner .evg-cta {
    color: red;
  }
```

- Use the ID selector of the outermost element for every CSS rule to scope them all to the specific template. Use classes instead of element names as selectors that follow the ID selector.

  ```css
  #evg-exit-intent-popup .evg-overlay {
    position: fixed;
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background-color: #000;
    opacity: 0.3;
  }

  #evg-exit-intent-popup .evg-popup {
    position: fixed;
    top: 50%;
    left: 50%;
    transform: translateX(-50%) translateY(-50%);
    width: 500px;
    height: 500px;
    padding: 20px;
    background-color: #fff;
    background-position: center bottom;
    background-size: cover;
    background-repeat: no-repeat;
  }
  ```

- When using multiple selectors for a ruleset, give each selector its own line.

  ```css
  #evg-banner .evg-header,
  #evg-banner .evg-subheader {
    margin-bottom: 1rem;
    text-align: center;
  }
  ```

- Write code in lowercase, including selectors, properties, and property values (except for strings).

  ```
/* bad */
  #evg-banner .evg-message {
    color: #CED5DF;
  }

  /* good */
  #evg-banner .evg-message {
    color: #ced5df;
  }
```

- Avoid using element names in conjunction with IDs or classes. Also avoid using ancestor selectors unless necessary.

  ```css
  /* bad */
  div#evg-banner {
    color: red;
  }

  /* good */
  #evg-banner {
    color: red;
  }

  /* bad */
  body div .evg-cta {
    color: red;
  }

  /* good */
  .evg-cta {
    color: red;
  }
  ```

- Don't add units for "0" values, unless required.

  ```css
  /* bad */
  p {
    margin: 0px 10px;
  }

  /* good */
  p {
    margin: 0 10px;
  }
  ```

- Don't add leading zeros in property values.

  ```
/* bad */
  p {
    font-size: 0.9rem;
  }

  /* good */
  p {
    font-size: .9rem;
  }
```

### Declaration Order

Group properties by type, in the following order:

1. Positioning
2. Display / Box Model
3. Color
4. Text
5. Other

Example:

```css
#evg-home-hero-banner .evg-btn {
  position: absolute; /* Positioning */
  z-index: 10; /* Positioning */
  top: 0; /* Positioning */
  left: 0; /* Positioning */
  display: inline-block; /* Display and Box Model */
  box-sizing: border-box; /* Display and Box Model */
  width: 100px; /* Display and Box Model */
  margin-bottom: 10px; /* Display and Box Model */
  padding: 10px 5px; /* Display and Box Model */
  border-radius: 5px; /* Display and Box Model */
  color: #fff; /* Color */
  background-color: #215ca0; /* Color */
  font-size: 16px; /* Text */
  font-family: Arial, sans-serif; /* Text */
  text-align: center; /* Text */
  text-transform: uppercase; /* Text */
  transition: color 0.15s; /* Other */
  cursor: pointer; /* Other */
  user-select: none; /* Other */
}
```

### Comments

Use `/* ... */` for comments.

```
/* Comment goes here */
p {
  color: white;
  background-color: blue;
}
```

```
/**
 * Comment
 * goes
 * here
 */
p {
  color: red;
}
```

## Client-side JavaScript

### ES Version

Global templates are written in ES6 syntax. Use ES5 syntax if there are plans to support IE browsers.

### Syntax

- Indent nested elements by 4 spaces (one press of the TAB key in the template editor).
- Break long lines to improve readability, up to 120 characters maximum per line (including whitespace).
- Add spaces between curly brackets and their contents.

  ```javascript
  // bad
  const foo = {company: ‘Salesforce’}

  // good
  const foo = { company: ‘Salesforce’ }
  ```

- No spaces between square brackets and their contents.

  ```javascript
  // bad
  const foo = [ a, b, c ];

  // good
  const foo = [a, b, c];
  ```

- No spaces between parentheses and their contents.

  ```javascript
  // bad
  console.log( foo );

  // good
  console.log(foo);

  // bad
  if ( bar ) {
    console.log(bar);
  }

  // good
  if (bar) {
    console.log(bar);
  }
  ```

- No space between the function name and opening parenthesis of the argument list.

  ```javascript
  // bad
  function foo () {
    console.log("foo");
  }

  // good
  function foo() {
    console.log("foo");
  }
  ```

- Add one space before the leading brace.

  ```javascript
  // bad
  function foo(){
    console.log("foo");
  }

  // good
  function foo() {
    console.log("foo");
  }

  // bad
  if (foo){
    console.log(foo);
  }

  // good
  if (foo) {
    console.log(foo);
  }
  ```

- Add one space before the opening parenthesis in conditional statements.

  ```javascript
  // bad
  if(foo) {
    console.log(foo);
  }

  // good
  if (foo) {
    console.log(foo);
  }
  ```

- When chaining more than two methods, separate each method by a new line and use indentation.

  ```javascript
// bad
  SalesforceInteractions.cashDom(".evg-cta").closest(".evg-jumbotron").find(".evg-header").text("Recommended For You").css("text-align", "left");

  // good
  SalesforceInteractions.cashDom(".evg-cta")
      .closest(".evg-jumbotron")
      .find(".evg-header")
      .text("Recommended For You")
      .css("text-align", "left");
```

  ```javascript
// bad
  Evergage.cashDom(".evg-cta").closest(".evg-jumbotron").find(".evg-header").text("Recommended For You").css("text-align", "left");

  // good
  Evergage.cashDom(".evg-cta")
      .closest(".evg-jumbotron")
      .find(".evg-header")
      .text("Recommended For You")
      .css("text-align", "left");
```

### DOM Manipulation

Use `cashDom` to select and manipulate elements from the DOM in a similar fashion to jQuery.

```javascript
SalesforceInteractions.cashDom(selector: <string>, context) => Cash
```

```javascript
Evergage.cashDom(selector: <string>, context) => Cash
```

Visit the [Cash](https://kenwheeler.github.io/cash/#docs) documentation to learn more.

### Deferred Rendering

Depending on the SDK namespace you're using, use `SalesforceInteractions.DisplayUtils.pageElementLoaded` or `Evergage.DisplayUtils.pageElementLoaded` to defer the rendering of the template until the content zone element is loaded on page. To use this utility, you must have the Display Utilities gear installed and enabled for your dataset.

The observer element that monitors for the content zone element to get inserted into its DOM node is set to "body" by default. For performance optimization, this default can be overridden by adding a second selector argument, which is used as the observer element instead.

```javascript
return SalesforceInteractions.DisplayUtils.pageElementLoaded(selector).then(function (element) {
  const html = template(context);
  SalesforceInteractions.cashDom(element).html(html);
  applyTheme(context);
});
```

```javascript
return Evergage.DisplayUtils.pageElementLoaded(selector).then(function (element) {
  const html = template(context);
  Evergage.cashDom(element).html(html);
  applyTheme(context);
});
```

Visit the [Template Display Utilities](https://developer.salesforce.com/docs/marketing/personalization/guide/web-template-display-utilities.md) documentation to learn more.

### Comments

Follow the [JSDoc](https://jsdoc.app/about-getting-started.html) standards for adding JavaScript documentation comments.

Use `//...` for inline comments.

```javascript
const foo = function () {
  const x = 4;
  const y = x + 2; // assign the sum of x + 2 to y
};
```

Use `/** ... */` to comment code blocks, placed it immediately before the block being documented. For multi-line comments, align the stars by indentation.

```javascript
/** Comment goes here */
if (foo) {
  console.log(foo);
}

/**
 * Comment
 * goes
 * here
 */
function foo(context) {
  console.log(foo);
}
```

Document code blocks with one or more JSDoc tags to describe the function.

```javascript
/**
 * @function incrementDate
 * @description Increment the date by a given number of days.
 * @param {string} date - The date, in MM/DD/YYYY format.
 * @param {number} days - The number of days to increment by.
 * @return {string} The new date, in MM/DD/YYYY format.
 */
function incrementDate(date, days) {
  // ..
}
```

See the complete list of [JSDoc tags](https://jsdoc.app/index.html#block-tags).

## Accessibility

### Semantic Elements

Use HTML elements for their designed purpose. Whenever possible, use semantic elements to describe the meaning of the content to developers and the browser when appropriate. For example, use heading elements such as `h1`, `h2`, and so on to identify headings, anchor elements (`a`) for navigation between pages, button elements (`button`) for actions like opening a modal, and input elements (`input`) for submit buttons (with the `type="submit"` attribute).

Semantic element examples:

- `button`
- `h1`
- `form`
- `header`

Non-semantic element examples:

- `div`
- `span`

If you use non-semantic elements instead of semantic elements, add ARIA attributes to provide more meaning to the element. For example, if you use a `div` element instead of the `h1` element as a level 1 heading and there is more than one heading on the page, add the `role="heading"` and `aria-level="<heading level number>"` ARIA attributes to the non-semantic element (for example, `<div role="heading" aria-level="1">Page Heading</div>`). Doing so allows assistive technologies like screen readers to identify the non-semantic element as a heading.

Provide an `alt` attribute for all image elements. In case an image fails to load, the text alternative can convey the meaning of the image in its place (for example, `alt="Woman with a shopping cart"`). Aim for succinct, descriptive text. If the image is used purely for decoration and is not informative, set the `alt` tag to an empty string (for example, `alt=""`) so that it can be ignored by assistive technologies. Do not leave out the `alt` attribute as some screen readers resort to announcing the file name of the image.

For close buttons ('X') such as those commonly used in popups, use a button element (`button`) with an `aria-label` attribute (for example, `aria-label="Close"`) to provide an accessible name.

The [WAVE Evaluation Tool](https://chromewebstore.google.com/detail/wave-evaluation-tool/jbbplnpkjmmeebjpijfedlgcdilocofh) Chrome extension is useful for evaluating the accessibility of your site.

For more information on accessibility, visit [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG21/).

### Making Accessible Color Choices

Ensure that the colors chosen for the text and background satisfy the color contrast ratio as recommended by Web Content Accessibility Guidelines (WCAG). Aim for a color contrast ratio of 4.5 or higher for normal text and 3 for larger text (18 px in bold or 24 px). Visit the [WCAG documentation](https://www.w3.org/TR/WCAG21/#contrast-minimum) on minimum contrast to learn more.

Use a tool like [aremycolorsaccessible.com](https://aremycolorsaccessible.com/) to check that the color ratio meets at least the AA level.

When using a background image as the backdrop for text, set a fallback background color in case the image does not load. Choose the fallback color such that the text is still visible and the colors meet the color contrast ratio requirements.

Example:

```css
#evg-hero-banner {
  background-image: url(‘image.png’);
  background-color: green;
}
```