Flow object

Important

The Boxever JavaScript Library is no longer receiving updates. We recommend that you upgrade to the Sitecore Engage SDK to get future updates and enhancements.

If you integrate with Sitecore CDP using the Boxever JavaScript Library or direct HTTP requests, use the flow object to collect identifying data about a user, and the friendlyID of an Interactive Full Stack Experience or an Interactive Full Stack Experiment that you want to run for the user. You then send the object to Sitecore CDP, and Sitecore CDP runs the experience or experiment.

Required attributes for flow objects

At a minimum, every flow object must include the following attributes plus one guest identifier attribute:

Attribute	Type	Description	Example	Required/optional
`clientKey`	string	Your client key.	`"ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe"`	Required
`friendlyId`	string	The ID of a live Interactive Full Stack Experience or live Interactive Full Stack Experiment that you want to run.	`"running_shoes_popup_02"`	Required
`channel`	string (uppercase)	The touchpoint where the user interacts with your brand. For example, for webpages, the channel is `"WEB"`. For mobile app screens, the channel is `"MOBILE_APP"`. If you don't set a value, the channel of the experience or experiment will be `"WEB"`.	Must be one of: `"AIRPORT_KIOSK"` `"BRANCH"` `"CALL_CENTER"` `"EMAIL"` `"GDS"` `"KIOSK"` `"MOBILE_APP"` `"MOBILE_WEB"` `"SMS"` `"OFFLINE"` `"OTA"` `"OTHER"` `"WEB"`	Required
`language`	string (uppercase ISO 639-1)	The language the user is using your app in. For example, if the user selects the Japanese language on your website, the language is `"JA"`.	`"DE"` `"EN"` `"FR"`	Required
`currencyCode`	string (uppercase ISO 4217)	The alphabetic currency code of the currency the user is using in your app. For example, if the user selects Australian dollars as the currency on your website, the currency is `"AUD"`.	`"EUR"` `"GBP"` `"USD"`	Required
`pointOfSale`	string	The name of the point of sale where the interaction with your brand takes place. You must set this value to the name of a point of sale that exists in your instance of Sitecore CDP.	`"myretailsite/ireland"`	Required

In addition to the attributes listed above, the flow object must also include one of the following guest identifier attributes:

Attribute	Type	Description	Example	Required/optional
`browserId`	string	The browser ID. If you are using the Boxever JavaScript Library, set the value to the value that the `Boxever.getID()` function returns: `browser_id: Boxever.getID()` If you are using direct HTTP requests, set the value to the value that was returned when you retrieved the browser ID.	The browser ID is a string similar to: `"a38b230c-11eb-4cf9-8d5d-274e9f344925"`	Required if none of the other attributes in this table are part of the flow object.
`email`	string (lowercase recommended)	The email address of the guest.	`"[email protected]"`	Required if none of the other attributes in this table are part of the flow object.
`identifiers`	array of objects	The identifiers that are used to identify the users of your app.	RequestResponse `identifiers: [{ "id": "123456", "provider": "BXLP" }]`	Required if none of the other attributes in this table are part of the flow object.

Attribute

Type

Description

Example

Required/optional

browserId

string

The browser ID.

If you are using the Boxever JavaScript Library, set the value to the value that the Boxever.getID() function returns: browser_id: Boxever.getID()

If you are using direct HTTP requests, set the value to the value that was returned when you retrieved the browser ID.

The browser ID is a string similar to:

"a38b230c-11eb-4cf9-8d5d-274e9f344925"

Required if none of the other attributes in this table are part of the flow object.

email

string (lowercase recommended)

The email address of the guest.

"[email protected]"

Required if none of the other attributes in this table are part of the flow object.

identifiers

array of objects

The identifiers that are used to identify the users of your app.

RequestResponse

identifiers: [{
    "id": "123456",
    "provider": "BXLP"
}]

Required if none of the other attributes in this table are part of the flow object.

The identifiers array of objects:

Attribute	Type	Description	Example	Required/optional
`id`	string	The unique guest identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system.	`"123456"`	Required
`provider`	string	The name of your organization's identity system, external to Sitecore CDP, that provided the unique guest identifier.	`"BXLP"`	Required
`expiry_date`	string (ISO 8601)	The date the unique guest identifier expires. This is determined by your organization's identity system.	`"2024-04-15T08:39:44.868Z"`	Optional

Optional attributes for flow objects

The flow object can optionally contain custom objects of your choice:

Attribute	Type	Description	Example	Required/optional
`params`	object	An object of your choice.	`params: { key: "value" }`	Optional

Examples

This example describes a flow object in an integration that uses the Boxever JavaScript Library. The flow object uses the browserId as the guest identifier. It also contains optional custom objects.

RequestResponse

const flowObject = {
    clientKey: Boxever.getClientKey(),
    friendlyId: "running_shoes_popup_02",
    channel: "WEB",
    language: "EN",
    currencyCode: "EUR",
    pointOfSale: "myretailsite/ireland",
    // guest identifier:
    browserId: Boxever.getID(),
    // optional attributes:
    aCustomObject1: { key: "value" },
    aCustomObject2: { isOptional: true }
}

This example describes a flow object in an integration that uses the Boxever JavaScript Library. The flow object uses the email as the guest identifier.

RequestResponse

const flowObject = {
    clientKey: Boxever.getClientKey(),
    friendlyId: "running_shoes_popup_02",
    channel: "WEB",
    language: "EN",
    currencyCode: "EUR",
    pointOfSale: "myretailsite/ireland",
    // guest identifier:
    email: "[email protected]"
}

This example describes a flow object in an integration that uses the Boxever JavaScript Library. The flow object uses the identifiers array of objects as the guest identifier.

RequestResponse

const flowObject = {
    clientKey: Boxever.getClientKey(),
    friendlyId: "running_shoes_popup_02",
    channel: "WEB",
    language: "EN",
    currencyCode: "EUR",
    pointOfSale: "myretailsite/ireland",
    // guest identifier:
    identifiers: [{
        id: "123456",
        provider: "BXLP",
    }]
}

Do you have some feedback for us?

If you have suggestions for improving this article,