saasco-sdk 0.2.5 → 0.2.6

package/README.md

@@ -287,6 +287,36 @@ saasco.disableDebug();
 
 The SDK can load Facebook Pixel, TikTok Pixel, and Pinterest Tag and forward `track` / `identify` calls to them. Map your Saasco event names to each network's standard events.
 
+When the same conversion is also sent by your server, include a stable `event_id`
+in the browser event properties and use that ID in the server API event:
+
+```ts
+saasco.track("Activated subscription", {
+  event_id: `${checkoutSessionId}:trial`,
+  currency: "USD",
+  value: 29,
+});
+```
+
+The SDK forwards this as Meta's `eventID` option, TikTok's `event_id` option,
+and Pinterest's `event_id` property. The mapped browser event name must also
+match the server event name. Use a different ID for each distinct conversion;
+the SDK does not generate conversion IDs or send server-side CAPI events.
+
+In the browser, events with a nonempty `event_id` are guarded per project,
+event name and destination for the current browser tab session. Concurrent calls
+share an in-flight dispatch. Only successful Saasco ingestion or a call to a
+loaded pixel runtime consumes that destination's guard; failed destinations can
+be retried by calling `track` again or revisiting the return page. With storage
+blocked, the guard lasts only until reload. Events without IDs are unchanged.
+
+Integrations initialize concurrently and each ready destination drains its own
+queue. Scripts and queued events have a bounded 10-second wait. Script stubs do
+not count as readiness. A script that fails to initialize can be retried by
+reloading after it is unblocked. Pixel dispatch is not proof of network receipt;
+verify receipt and browser/server deduplication in each advertising dashboard.
+`track()` still reports Saasco ingestion status, not advertising receipt.
+
 ```ts
 export const saasco = new Saasco({
   projectId: "YOUR-PROJECT-ID",
@@ -496,6 +526,7 @@ window.SaascoSupport.open();
 - `registerTool({ name, execute })` — register a **client tool** the agent can
   call; it runs in your page (see [Tools](#tools)).
 - `open()` / `close()`.
+- `setBottomPadding(px)` — lift the launcher and the open panel by `px` (Intercom `setBottomPadding`). Bottom-docked chrome can instead set `data-saasco-bottom-inset` on itself; the loader measures that element when it overlaps the launcher's corner and uses the larger of the two.
 
 The analytics script injects the loader asynchronously, so `window.SaascoSupport`
 appears a tick after your inline script runs. Wait for it before calling the API: