Skip to main content

Config API Documentation

The Config API is responsible for generating unique identifiers required for personalizing content and capturing user trends. These identifiers include the customer ID and session ID, which are randomly generated and do not contain any personal data.

Customer ID and Session ID Management​

Customer ID​

  • A new customer ID must be generated for each new customer.
  • This ID remains consistent across sessions.

Session ID​

  • A new session ID should be created for each session.
  • A session starts when the user opens your website or app, or when their previous session times out.
  • Sessions time out after 30 minutes of inactivity, which must be managed on the client side.

Client-Side Session Management​

The client application should manage the session lifecycle using the duration (in milliseconds) provided in the response when generating the session ID. Store the session ID in a cookie with the recommended expiration.

On Each Page Load​

  • If the session is still active: Extend the session by resetting the expiration timer based on the recommended duration.
  • If the session has expired: Generate a new session ID by calling the /3.0/config endpoint with the existing customer ID, associating the new session with the current customer.

Server-Side Considerations​

  • The server does not enforce session expiration.
  • Session IDs are stored indefinitely for reporting purposes but are not used to track session activity.
  • Active session management, including expiration and renewal, is entirely handled by the client.
  • Session duration and refresh rules should be governed by the client-side implementation based on the recommended duration provided in the API response.

API Endpoint​

Method​

GET

URL​

https://<PA_END_POINT>/3.0/config

Headers​

  • Content-Type: application/json
  • Authorization: Bearer ACCESS_TOKEN

Query Parameters​

  • customerId: If generating a session ID for an existing customer, provide the current customer ID; otherwise, skip this parameter.
  • isMobile: If creating a new customer ID and the user is browsing from a mobile device, set it to true; otherwise, skip this parameter.

Returned Payload​

{
    "payload": {
        "customerId": "xxxxxxxxxxxxxx",
        "session": {
            "id": "xxxxxxxxxxxxxx",
            "duration": 1800000
        },
        "controlCohort": true
    },
    "type": 1,
    "code": 0 
}
  • payload.customerId: If a specific customer ID was provided during the API call, that same customerId will be returned; otherwise a newly generated one will be returned.
  • payload.session: This includes the unique sessionID and its duration, which gets cached within system memory - note that sessions do not expire.
  • payload.controlCohort: Indicates whether or not customers have been placed in control cohorts on your website; returns true if they are part of this cohort or false if not.
  • type: A system parameter always designated as 1 for successful responses
  • code: Another system parameter is always set at zero when there's no issue with processing requests

Example Usage (JavaScript)​

const myHeaders = new Headers();
myHeaders.append("Authorization", "ACCESS_TOKEN");
myHeaders.append("Content-Type", "application/json");

const requestOptions = {
    method: 'GET',
    headers: myHeaders,
    redirect:'follow'
};

fetch('https://<PA_END_POINT>/3.0/config', requestOptions)
    .then(response => response.json())
    .then(result => console.log(result))
    .catch(error => console.error(error));

Summary​

This document discusses the necessity of customer and session IDs for personalizing content, as well as the process of generating and managing these IDs.

  • Customer and session IDs are essential for personalization and user trend capture, generated via the Config API call.
  • A new customer ID is required for each new customer, while a new session ID should be created for every new session.
  • The default session duration is 30 minutes of inactivity, but can be managed based on best practices.
  • The GET method with specific headers and query parameters is used to generate customer and session IDs.
  • The returned payload includes the generated or existing customer ID, unique session ID with its duration, and other system parameters.