SDK Events
Reference for handling events emitted by the Postscript SDK
The Postscript SDK emits various events to track customer interactions with popups on your site. These events enable developers to integrate and respond to these interactions effectively, allowing for tracking, analytics, and custom behaviors that enhance your application's engagement and data collection capabilities.
Additionally, the SDK includes a postscriptReady
event, which signals when the Postscript SDK is fully loaded and ready for use.
Postscript Ready (postscriptReady
)
postscriptReady
)The postscriptReady
event triggers when the Postscript SDK has fully loaded and is ready for use. This event ensures that functions from the SDK are called only after the SDK is fully initialized.
Popup Events (postscriptPopup
)
postscriptPopup
)The postscriptPopup
event is triggered when a customer interacts with a popup on your site. This event contains different types depending on the action taken.
Impression (impression
)
impression
)The "impression" event triggers whenever the popup is displayed to a customer. It includes an isReopen
attribute that is true if the impression is due to a previously minimized popup being reopened.
Event Details Structure
- type: The type of event fired. For popup impression events, this value is "impression".
- popupId: The ID of the popup that fired the event.
- popupName: The name of the popup that fired the event.
- isReopen: A boolean indicating if the impression is due to a previously minimized popup being reopened.
Example:
{
"detail": {
"type": "impression",
"popupId": 42,
"popupName": "Mobile + Onsite Opt-In",
"isReopen": false
}
}
Form Submission (formSubmit
)
formSubmit
)The "formSubmit" event triggers when a form within a popup is submitted.
Event Details Structure
- type: The type of event fired. For form submissions, this value is "formSubmit".
- popupId: The ID of the popup that fired the event.
- popupName: The name of the popup that fired the event.
- values: The values of elements in the popup form. This includes:
- email: The email if submitted as part of the form.
- phone: The phone number if submitted as part of the form.
- Custom Data: Data from other questions in the form will be included using the name of the subscriber property that is mapped to the question.
Example:
{
"detail": {
"type": "formSubmit",
"popupId": 42,
"popupName": "Mobile + Onsite Opt-In",
"values": {
"phone": "15558675309",
"gender": "female"
}
}
}
Close (close
)
close
)The "close" event triggers when a popup is closed by the user. It includes an attribute to indicate whether the popup was hard closed or minimized.
Event Details Structure
- type: The type of event fired. For popup close events, this value is "close".
- popupId: The ID of the popup that fired the event.
- popupName: The name of the popup that fired the event.
- hard: A boolean value indicating whether the popup was hard closed (true) or soft closed (false). A popup that is hard closed is completely removed. A popup that is soft closed is minimized to the bottom of the screen.
Example:
{
"detail": {
"type": "close",
"popupId": 42,
"popupName": "Mobile + Onsite Opt-In",
"hard": true
}
}
Subscriber Created (subscriberCreated)
The "subscriberCreated" event triggers when a new subscriber is created after completing an onsite opt-in. This event provides information about the newly created subscriber and any promotional codes that are available to them.
Event Details Structure
- type: The type of event fired. For subscriber creation events, this value is "subscriberCreated".
- popupId: The ID of the popup that fired the event.
- popupName: The name of the popup that fired the event.
- subscriberId: The ID of the subscriber created through the popup.
- discountCode: The discount code, if any, available to this new subscriber.
- cashbackCode: The cashback promotion code, if any, available to this new subscriber.
- autoApplyOfferEnabled: A boolean value indicating whether the discount code should be auto-applied to the user's cart.
{
"detail": {
"type": "subscriberCreated",
"popupId": 42,
"popupName": "Mobile + Onsite Opt-In",
"subscriberId": "12345",
"discountCode": "WELCOME10",
"cashbackCode": "CASHBACK5",
"autoApplyOfferEnabled": true
}
}
Use Cases
Postscript Ready Event
window.addEventListener("postscriptReady", function(ev) {
window.postscript.identify({
phone: "555-555-5555"
});
});
Track Popup Impression to Google Tag Manager
window.addEventListener("postscriptPopup", function(ev) {
if (ev.detail.type === 'impression') {
const { popupName, popupId, isReopen } = ev.detail;
// Prepare data for GTM dataLayer
const dataLayerEvent = {
event: 'postscript_popup_impression',
popup_name: popupName,
popup_id: popupId,
is_reopen: isReopen
};
// Push the event data to the dataLayer
window.dataLayer = window.dataLayer || [];
window.dataLayer.push(dataLayerEvent);
}
});
Track Form Submission to Google Tag Manager
window.addEventListener("postscriptPopup", function(ev) {
if (ev.detail.type === 'formSubmit') {
const { values, popupName, popupId } = ev.detail;
// Prepare data for GTM dataLayer
const dataLayerEvent = {
event: 'postscript_form_submit',
popup_name: popupName,
popup_id: popupId,
...values
};
// Push the event data to the dataLayer
window.dataLayer = window.dataLayer || [];
window.dataLayer.push(dataLayerEvent);
}
});
Track Popup Close to Google Tag Manager
window.addEventListener("postscriptPopup", function(ev) {
if (ev.detail.type === 'close') {
const { popupName, popupId, hard } = ev.detail;
// Prepare data for GTM dataLayer
const dataLayerEvent = {
event: 'postscript_popup_close',
popup_name: popupName,
popup_id: popupId,
hard_close: hard
};
// Push the event data to the dataLayer
window.dataLayer = window.dataLayer || [];
window.dataLayer.push(dataLayerEvent);
}
});
Track Subscriber Creation to Google Tag Manager
window.addEventListener("postscriptPopup", function(ev) {
if (ev.detail.type === 'subscriberCreated') {
const { popupId, popupName, subscriberId, discountCode, cashbackCode, autoApplyOfferEnabled } = ev.detail;
// Prepare data for GTM dataLayer
const dataLayerEvent = {
event: 'postscript_subscriber_created',
popup_name: popupName,
popup_id: popupId,
subscriber_id: subscriberId,
discount_code: discountCode,
cashback_code: cashbackCode,
auto_apply_offer_enabled: autoApplyOfferEnabled
};
// Push the event data to the dataLayer
window.dataLayer = window.dataLayer || [];
window.dataLayer.push(dataLayerEvent);
}
});
Updated 2 months ago