Using `perselioReady`

perselioReady is the recommended way to run your code once the Perselio SDK is fully initialized and ready to use.

It works safely in all situations:

before the SDK script is loaded,
while it is loading,
and after it is already initialized.

Your callback will always be executed exactly once, with the Perselio public API passed as an argument.

Bootstrap Snippet

Place this snippet before loading the Perselio SDK:

<script>
  window.perselioReady =
    window.perselioReady ||
    function (cb) {
      (window._perselioReady = window._perselioReady || []).push(cb);
    };
</script>

This creates a lightweight stub that queues callbacks until the SDK is ready.

Registering a Callback

You can now safely register a callback anywhere on the page:

window.perselioReady(async function (perselio) {
  const result = await perselio.client.recommendation.getRecommendation({
    scenario: {
      scenarioId: "example_scenario",
      itemId: "ITEM_123",
    },
    filters: [{ filterId: "availability-filter", available: true }],
    includeFields: ["url", "itemId", "name"],
    limit: 3,
  });

  console.log(result);
});

When the SDK is ready, your callback receives the perselio API object and can immediately start making requests.

Example response:

{
  "recommendationId": "abc12345-0000-0000-0000-000000000000",
  "items": [
    {
      "itemId": "ITEM_A",
      "name": "Sample Product A",
      "url": "https://example.com/product-a"
    },
    {
      "itemId": "ITEM_B",
      "name": "Sample Product B",
      "url": "https://example.com/product-b"
    },
    {
      "itemId": "ITEM_C",
      "name": "Sample Product C",
      "url": "https://example.com/product-c"
    }
  ],
  "totalItemsCount": 42
}

Automatic Identification & Deduplication

Every recommendation request sent through the Perselio SDK is automatically enriched with identification data. You do not need to provide these values manually.

The SDK injects:

zoeId — anonymous browser identifier
userId — known user identifier (if available)
pageInstanceId — unique identifier of the current page instance, used for deduplication

These identifiers allow Perselio to:

personalize results consistently across pages and sessions,
avoid returning duplicate items within a single recommendation response,
correlate requests for analytics and optimization.

You can focus purely on describing what you want to recommend; Perselio handles who the recommendation is for.

Scenarios & Parameters

The scenario object defines what type of recommendation you are requesting and which contextual parameters should be used.

Each scenario represents a distinct recommendation strategy and accepts a specific set of parameters. The most common fields are:

itemId — contextual item (e.g. the product currently viewed)
cartItemsIds — list of item IDs currently in the cart
categoryId — category context

Example scenarios (non-exhaustive):

`quick_picks`

Fast, context-aware picks for the current item.

{
  scenarioId: 'quick_picks';
  itemId: string;
  cartItemsIds?: string[] | null;
  categoryId?: string | null;
}

`recommended_for_you`

Personalized recommendations for the current user, optionally contextualized by page state.

{
  scenarioId: 'recommended_for_you';
  itemId?: string | null;
  cartItemsIds?: string[] | null;
  categoryId?: string | null;
}

`accessories`

Accessory or complementary items for a specific product.

{
  scenarioId: 'accessories';
  itemId: string;
  cartItemsIds?: string[] | null;
  categoryId?: string | null;
}

`pre_cart`

Recommendations triggered when an item is added to the cart.

{
  scenarioId: 'pre_cart';
  itemId: string;
  cartItemsIds?: string[] | null;
  categoryId?: string | null;
}

The complete and authoritative specification is available here:

API reference: https://docs.perselio.com/reference/getrecommendation
Conceptual overview: https://docs.perselio.com/docs/reco-widgets

These documents describe:

all supported scenario types,
required and optional parameters for each scenario,
available filters and their semantics,
response structure and pagination behavior.

Always consult the reference when introducing a new scenario type to ensure that your request matches the expected schema.

Guarantees

Your callback is never lost, even if registered before the SDK loads.
If the SDK is already initialized, the callback runs immediately.
Errors inside your callback do not affect the SDK or the page.
Multiple callbacks can be registered independently.

This pattern is ideal for embedding Perselio on third-party sites where script load order cannot be guaranteed.

GTM integration

If GTM/dataLayer integration is enabled for the SDK setup, Perselio can push a perselio.ready event to window.dataLayer after initialization.

This lets you consume Perselio identification values directly in GTM (for example in custom variables, tags, or triggers).

Example payload:

{
	"event": "perselio.ready",
	"perselio": {
		"identification": {
			"zoeId": "<ANONYMOUS_ID>",
			"userId": "<USER_ID>",
			"pageInstanceId": "<PAGE_INSTANCE_ID>"
		}
	}
}

Notes:

The event is optional and depends on integration configuration.
userId may be missing or empty for anonymous users.

Using perselioReady