SDK API Reference
The API Reference for our JavaScript SDK
window.postscript
When the SDK is installed properly, you should be able to reference it using window.postscript
.
window.postscript.identify
Identifies a subscriber on your site.
Usage:
window.postscript.identify({
phone: "555-555-5555"
});
Payload | Description |
---|---|
{ "phone": "555-555-5555" } | A JSON payload object to use to identify the subscriber. It must have a phone field to look the subscriber up by. |
Returns result indicating whether or not a subscriber was found and if so, that they were cookied.
window.postscript.getSubscriberId
Returns a Postscript Subscriber ID if found.
Usage:
window.postscript.getSubscriberId();
window.postscript.event
Fires an event for a subscriber.
Usage:
window.postscript.event('event_name', payload);
Supported Events
Event Name | Description |
---|---|
page_view | Fires an event for Subscriber Viewed Product. For use in "Subscriber Viewed Product" automations (i.e. Browse Abandonment). |
add_to_cart | Fires an event for Product Added to Cart. For use in "Product Added to Cart" automations (i.e. Browse Abandonment). |
Payload Properties
Property | Description | Example |
---|---|---|
shop_id | Your Postscript shop_id for your account. | 123456 |
url | The URL of the page the event occurred on. This must be a full URL, not a relative URL, including the full domain. | https://example.myshopify.com/products/red-shoes |
search_params | An object representing the query parameters on the current URL. | { "variant" : "1935013205" } |
page_type | The type of page that the event occurred on. | product |
referrer | The referrer for the current page. This can be document.referrer for most integrations. | https://example.myshopify.com/collections/shoes |
resource | An object representing the product data. See properties below. | |
resource.category | The product type of the current product being viewed or added to cart. | Shoes |
resource.name | The title of the current product. | Red Shoes |
resource.price_in_cents | The price of the product in cents | 6500 |
resource.resource_id | The id of the product | 9250252 |
resource.resource_type | This will always be "product" | product |
resource.sku | The SKU of the current variant being viewed or added to cart, if available. | AF1RED-12 |
resource.variant_id | The SKU of the current variant being viewed or added to cart. | 1935013205 |
resource.vendor | The vendor of the product. | Nike |
Example Payload
{
"shop_id": "123456",
"url": "https://example.myshopify.com/products/antique-drawers",
"search_params": {
"variant": "123456789"
}
"page_type": "product",
"referrer": "https://example.myshopify.com/collections/all",
"resource": {
"category": "Indoor",
"name": "Antique Drawers",
"price_in_cents": 25000,
"resource_id": 123456789,
"resource_type": "product",
"sku": null,
"variant_id": 123456789,
"vendor": "Company 123"
}
}
window.postscript.popups.open
Opens a specified popup programmatically.
Usage:
window.postscript.popups.open(popupId, options);
Parameters
- popupId (required): The ID of the popup to open.
- options (optional): Configuration for when and how the popup is fired.
Options Properties
Property | Type | Description | Default |
---|---|---|---|
activePopupBehavior | string | Controls what happens to the currently open popup if a second popup is programmatically triggered. Possible values: ALWAYS_DISMISS , NEVER_DISMISS , DISMISS_WHEN_SOFT_CLOSED . | ALWAYS_DISMISS |
respectPopupStatus | boolean | Determines if the popup respects the status cookie. If true , popups previously dismissed won't show again (or will show in the close bubble if soft closed). If false , the popup will open regardless of any prior dismissals. | true |
activePopupBehavior
Values
activePopupBehavior
ValuesALWAYS_DISMISS
: The first popup will be closed, and the programmatic popup will open.NEVER_DISMISS
: The first popup stays open, and the programmatic trigger is ignored.DISMISS_WHEN_SOFT_CLOSED
: The programmatic popup only opens if the first popup was in the close bubble state.
Example
window.postscript.popups.open(123456, {
activePopupBehavior: 'ALWAYS_DISMISS',
respectPopupStatus: false
});
window.postscript.popups.find
Finds the most appropriate popup to display based on the current page, user, and other criteria.
Usage:
window.postscript.popups.find(options);
Parameters
- options (optional): Criteria used to determine the best popup to show.
Options Properties
Property | Type | Description | Default |
---|---|---|---|
type | string | Filters results by popup type (legacy or standard ). | undefined (returns all) |
triggerType | string | Filters by trigger type (Custom or Delay ). | Custom |
respectPage | boolean | If true , only considers popups allowed on the current page. | true |
respectSubscriber | boolean | If true , only considers popups allowed for current subscriber status. | true |
respectCountry | boolean | If true , only considers popups allowed in the user's country. | true |
respectPlatform | boolean | If true , only considers popups allowed on the current platform. | true |
respectStatus | boolean | If true , only considers popups that have not been hard closed. | true |
Returns
A Promise resolving to the best popup’s ID (number or string) if found, or undefined if no matching popup is available.
Example
window.postscript.popups.find({
triggerType: 'Custom',
respectPage: true,
respectSubscriber: true,
respectCountry: true,
respectPlatform: true,
respectStatus: true
}).then((popupId) => {
if (popupId) {
window.postscript.popups.open(popupId);
}
});
Examples
Show popup on element click
function initializePopup() {
if (!window.postscript || typeof window.postscript !== "object" ||
typeof window.postscript.popups?.find !== "function" ||
typeof window.postscript.popups?.open !== "function") {
return; // Postscript SDK isn't fully ready
}
// Find the best popup to show
window.postscript.popups.find().then((popupId) => {
if (!popupId) return;
function attachClickEvent(button) {
button.addEventListener("click", function() {
window.postscript.popups.open(popupId);
});
}
let button = document.getElementById("my_button");
if (button) {
attachClickEvent(button);
} else {
// Wait for the button to be added to the DOM
const observer = new MutationObserver((mutations, obs) => {
button = document.getElementById("my_button");
if (button) {
attachClickEvent(button);
obs.disconnect(); // Stop observing once button is found
}
});
observer.observe(document.body, { childList: true, subtree: true });
}
});
}
// Check if Postscript SDK is already available
if (window.postscript && typeof window.postscript === "object" &&
typeof window.postscript.popups?.find === "function" &&
typeof window.postscript.popups?.open === "function") {
initializePopup();
} else {
// Wait for Postscript to be ready
window.addEventListener("postscriptReady", initializePopup);
}
Updated 11 days ago