When end users' browsers send requests directly to Constructor, those requests include the User-Agent and X-Forwarded-For headers. Constructor uses these headers to identify the source of each request, which is required for DDoS protection. In a backend integration, servers send requests to Constructor on behalf of end users, so these headers are not automatically populated with end-user information and must be forwarded explicitly.

❗️

It is imperative that X-Forwarded-For and User-Agent headers are included with all requests to Constructor.

In order to power personalization, an anonymous user identifier and session identifier are stored in the user's browser and automatically transmitted with requests in a frontend integration. In a backend integration, these values will need to be read from cookies and transmitted with requests.

The following data points should be sent with requests originating server side (backend integrations):

HTTP headers

X-Forwarded-For - mandatory

Containing the IP of the origin request from the user's browser. This must be a single IP indicating the client that issued the request (not a chain of comma separated IPs).

x-cnstrc-token - mandatory

A unique string supplied by Constructor to be transmitted with requests originating from the backend. This value should be treated as sensitive information and never exposed client side.

User-Agent - mandatory

Containing the User-Agent of the origin request from the user's device. This header is used for device identification and analytics.

Web (browser-based) integrations

Forward the User-Agent as-is from the end-user's browser.

Native app integrations (iOS)

• Format: [app_name]/[app_version] ([device]; CPU iPhone OS [os_version] like Mac OS X)
• Example: MyApp/3.2.1 (iPhone; CPU iPhone OS 17_6 like Mac OS X)

Alternatively, if your app uses URLSession and has access to the CFNetwork/Darwin version numbers:

• Format: [app_name]/[app_version] CFNetwork/[cfnetwork_version] Darwin/[darwin_version]
• Example: MyApp/3.2.1 CFNetwork/1474 Darwin/23.0.0

Native app integrations (Android)

• Format: [app_name]/[app_version] (Linux; Android [os_version]; [device_model])
• Example: MyApp/3.2.1 (Linux; Android 14; Pixel 8)

Key

• [app_name]/[app_version]: your application name and version (e.g., MyApp/3.2.1)
• [device]: the iOS device type: iPhone, iPad, etc.
• [os_version]: OS version using underscores for iOS (e.g., 17_6) or dots for Android (e.g., 14)
• [device_model]: the Android device model (e.g., Pixel 8, SM-G960U)

Query parameters

i,s - mandatory

Client and session parameters from ConstructorioID_client_id and ConstructorioID_session_id cookies, respectively

ui - mandatory for logged-in users

A unique internal identifier for a logged-in user. Used for cross device personalization

c

Specification of this parameter is only necessary when a client library is not being utilized.

This parameter identifies the client the request is coming from and it should have the following format: cio-[fe/be]-[platform]-[company name]

Where:

• [fe/be] indicates a frontend or backend integration
• [platform] indicates web or mobile platform
• [company name] indicates the name of the company (should correspond with company name in dashboard)

Examples:

• The request is coming from a website - cio-fe-web-farmstand
• The request is coming from a mobile app - cio-fe-mobile-farmstand
• The request is coming from a backend server - cio-be-web-farmstand

origin_referrer

The page URL of the originating client side request

_dt

Current UNIX timestamp of request (ex: 1634170420420)

Client libraries

The suite of Constructor client helper libraries simplify the process of sending the parameters listed in the context of a backend integration. For more detailed instructions on how to send the required backend parameters within each client library, please refer to the relevant GitHub Wiki entry: Node, Java, .NET, Python