Custom JS snippet

Prerequisites:

• Company or App Administrator permissions in Recurly Engage
• Familiarity with your site's user identification methods (localStorage, cookies, dataLayer)

Definition

Key benefits

Key details

Admin users may override the following functions on the Settings class. Upon deploying Recurly Engage for the first time, review and configure the functions relevant to your app to ensure users are recognized, tracked, and prompted correctly. You may need to work with your developers to determine the best method for each. Reach out to [email protected] if you need assistance.

fetchUserId() (required)

Returns the authenticated user's unique ID. This string can come from cookies, local storage, a database, or an async endpoint fetch. This function runs when the Recurly Engage JS tag loads.

static async fetchUserId() {
  const user = JSON.parse(localStorage.getItem("user_object"));
  return user.id;
}

fetchUserJwt()

Returns a JSON Web Token (JWT) for the current user, if your app issues one. Recurly Engage uses this to verify the user's identity for secure operations.

static async fetchUserJwt() {
  return window.userJwt;
}

fetchAnonUserId() (optional)

Returns a stable anonymous ID for unauthenticated users. If omitted, Recurly Engage automatically generates and assigns one.

static async fetchAnonUserId() {
  return JSON.parse(localStorage.getItem("ajs_anonymous_id"));
}

fetchUserTraits() (optional)

Returns an object of user traits to sync to Recurly Engage. Traits can come from cookies, local storage, a database, or an async endpoint fetch, and are used for segmentation, personalization, and reporting.

static async fetchUserTraits() {
  const user = JSON.parse(localStorage.getItem("user_object"));
  return {
    is_registered: !!user.token,
    member_since: user.registrationDate,
    accepted_tos: localStorage.getItem("tos_acceptance_date")
  };
}

canShowPromotion()

Specifies app-wide conditions under which prompts should never be shown. Returns a boolean — when false, no overlay prompts are shown. Unlike the other functions, this one is not async.

static canShowPromotion() {
  return !document.querySelector(".full-screen-video-player");
}

onPromptInteraction(eventName, payload)

Called whenever a prompt event occurs, for custom analytics purposes.

static onPromptInteraction(eventName, payload) {
  analytics.track(payload.activity, payload);
}

The payload object includes:

canPing()

Specifies whether the user has opted into being identified by Recurly Engage. Returns a boolean — use this to honor CCPA/GDPR opt-outs. When false, user information is not collected.

static canPing() {
  return true;
}

setLanguage()

Specifies the user's language, controlling the display language of prompts that have languages configured. Returns a 2-letter or 4-letter language code, or null to use the default.

static setLanguage() {
  return null;
}