>> ANCHOR_NAV_TEST_MODULE

YouLead QA Sandbox — System Overview

This sandbox is the primary integration testing environment for the YouLead Marketing Automation JavaScript API. It operates against the dev1 tenant and communicates exclusively with m-dev1.youlead.pl.

All events are dispatched through the window.ylData queue. The YouLead tracking script processes this queue asynchronously after injection. Each page loads the script dynamically via YouLeadHead.astro.

The sandbox is deployed on Vercel with an SSR adapter. Server-side routes live under /api/ and handle authenticated calls to the YouLead REST backend using HMAC-SHA1 signatures composed of ClientId, AppId, SecretKey, and a Unix timestamp.

All QA pages follow a terminal/CLI visual language: monospace fonts, emerald-on-black palette, uppercase labels, and bordered panels. This aesthetic is enforced via global CSS component classes defined in src/styles/global.css.

Page Events

Page events track navigation within a single-page context or signal a virtual pageview to the YouLead engine. They are pushed as { page: YlPagePayload }.

The extendedValue field attaches arbitrary metadata to the pageview. The reloadScripts boolean (default: false) forces re-evaluation of CRM personalization rules after the push. The referrer field overrides the detected referrer for attribution tracking.

Page events are typically used in SPA environments where the browser URL changes without a full page reload. In standard multi-page Astro builds, the YouLead script fires an implicit page event on every load — explicit page pushes are only needed for client-side navigation.

When using reloadScripts: true, be aware that CRM popups and HTML blocks may re-render, causing visible flicker in the UI. Use only when required by the test scenario.

Product View Events

Product view events signal that a contact has viewed a specific product page. Payload type: { product: YlProductPayload }. The products field is a string array of product IDs.

Product IDs may include a feed identifier using the @ separator — e.g., PROD-123@EN routes to the English-language product feed. This is required in multi-language catalog setups.

The public/products.csv file defines the product catalog available in this sandbox. It currently contains one entry: PROD-123 (QA Cyber-Implant, 100.00 PLN). If a productId sent in an event does not exist in the CRM importer, the event is silently discarded.

Test this event on /products/manual-test (fixed ID) or /products/manual-simulator (dynamic ID input).

Cart Events

Cart events update the contact's basket state in YouLead. Two operation modes exist: cart (replace entire cart) and cart.add (append items). Both accept the same YlCartPayload.

Each item in the products array is a YlProduct object with productId, optional quantity, price, and customValue.

Passing an empty array products: [] clears the cart. This is the canonical way to reset cart state before or after a purchase scenario.

Optional fields: transactionId, cartUrl, customValue. The cartUrl enables abandoned-cart recovery emails with a direct restore link.

Purchase Events

Purchase events record a completed transaction. Payload type: { purchase: YlPurchasePayload }. Required fields: products[] and userId (the contact's ylid cookie value).

The transactionId should be unique per order (e.g., TX-{Math.random()}). YouLead deduplicates on this ID — re-sending the same transactionId will not create a duplicate purchase record in the CRM.

Purchase cancellation uses a separate event type: { 'purchase.cancel': { transactionId } }. The transactionId must match an existing purchase to reverse it.

After a successful purchase, clear the cart via cart: { products: [] } in the callBack to keep local and CRM cart state in sync.

Custom Events

Custom events fire named tracking signals that trigger automation rules in the YouLead CRM. Payload type: { event: YlEventPayload }. The eventName must match a rule configured in the CRM dashboard.

Optional params field accepts a query-string-formatted string: key1=value1&key2=value2. These parameters enrich the event record and can be used in segmentation or personalization rules within the CRM.

This sandbox fires API_TEST_EVENT as the canonical test event. See /custom-events for the interactive trigger UI.

Survey responses use a dedicated type: { survey: { surveyId, answers: [] } }. Each answer specifies a questionId and either choiceId (select-type) or value (text-type).

Web Push Integration

Web Push requires three independent components to function: browser notification permission, a registered Service Worker, and a push subscription token linked to the YouLead backend.

The sandbox Service Worker at public/sw.js delegates to the YouLead-hosted worker via importScripts('https://m-dev1.youlead.pl/yl-sw.js'). This means push handling logic is maintained by YouLead, not this sandbox.

The manifest.json contains gcm_sender_id: "103953800507", required for Chrome to allow push subscription without an explicit VAPID applicationServerKey. Removing or changing this value breaks the FORCE_SUBSCRIPTION flow.

Diagnostic flow on /webpush: [1] request permission → [2] install SW → [3] force subscribe. Status panel auto-refreshes every 2 seconds to reflect SW and token state.

Dynamic Content

Dynamic Content is served by YouLead via the global window.YouLeadDynamicContent object, which is populated by the tracking script after initialization. Calling it before the script loads throws a ReferenceError.

InstantRequestById(name, parameter, width, height) fetches and renders a named content block identified by its UUID in the CRM content library. Width and height of 0 signal auto-sizing.

YouLeadDynamicContent.InstantRequestById(
  'c6f396b9-c9d0-439a-8b17-a63c3b0d5302',
  null, 0, 0
);

The ylCtaBtn.init method injects a floating CTA button anchored to the left or right edge of the viewport. Requires a styles URL from the YouLead CDN. Pages that use the yldynamiccontent CSS class on a container receive server-pushed content directly.

Callback Pattern for Playwright

YouLead processes events asynchronously. A Playwright test that asserts state immediately after ylData.push() will produce false positives — the event may not yet have reached the server.

Every push in this sandbox sets window.lastActionStatus = 'PENDING' before the push and window.lastActionStatus = 'SUCCESS' inside the callBack. Playwright tests must await this signal:

Reset the flag to 'IDLE' between test steps to prevent a previous SUCCESS from masking a missing callback in the next action.

This approach eliminates flaky timeout-based waits and gives 100% confirmation that the YouLead script received and processed the event before the test proceeds.

Troubleshooting