The Postscript SDK emits various events to track customer interactions with popups and embedded forms 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.

Popup interactions emit postscriptPopup events, while embedded forms emit postscript:embedded-form events.

Postscript Ready (`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`)

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`)

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`)

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`)

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
  }
}

Embedded Form Events (`postscript:embedded-form`)

The postscript:embedded-form event is triggered when a customer interacts with an embedded form on your site. This event contains different types depending on the action taken.

Mount (`mount`)

The "mount" event triggers when the embedded form has loaded its configuration and is ready for use.

Event Details Structure

type: The type of event fired. For embedded form mount events, this value is "mount".
shopId: The Postscript shop ID the form belongs to.
formId: The embedded form's unique identifier.
origin: The host page URL (window.location.href) at dispatch time.

Example:

{
  "detail": {
    "type": "mount",
    "shopId": 12345,
    "formId": "abc123",
    "origin": "https://example.com/pages/quiz"
  }
}

Impression (`impression`)

The "impression" event triggers when the embedded form becomes visible to the customer for the first time.

Event Details Structure

type: The type of event fired. For embedded form impression events, this value is "impression".
shopId: The Postscript shop ID the form belongs to.
formId: The embedded form's unique identifier.
origin: The host page URL (window.location.href) at dispatch time.

Example:

{
  "detail": {
    "type": "impression",
    "shopId": 12345,
    "formId": "abc123",
    "origin": "https://example.com/pages/quiz"
  }
}

Step Change (`step-change`)

The "step-change" event triggers whenever the embedded form transitions from one step to another in a multi-step flow.

Event Details Structure

type: The type of event fired. For embedded form step change events, this value is "step-change".
shopId: The Postscript shop ID the form belongs to.
formId: The embedded form's unique identifier.
origin: The host page URL (window.location.href) at dispatch time.
stepId: The ID of the step the user just entered.
stepName: The name of the step the user just entered.
previousStepId: The ID of the step the user came from.
previousStepName: The name of the previous step.

Example:

{
  "detail": {
    "type": "step-change",
    "shopId": 12345,
    "formId": "abc123",
    "origin": "https://example.com/pages/quiz",
    "stepId": "step_2",
    "stepName": "Phone Number",
    "previousStepId": "step_1",
    "previousStepName": "Welcome"
  }
}

Complete (`complete`)

The "complete" event triggers when a customer reaches the final step in their form flow.

This can happen when:

A customer completes the form and successfully subscribes.
A returning subscriber is automatically routed to a completed state.

Event Details Structure

type: The type of event fired. For embedded form completion events, this value is "complete".
shopId: The Postscript shop ID the form belongs to.
formId: The embedded form's unique identifier.
origin: The host page URL (window.location.href) at dispatch time.
subscriberId: The Postscript subscriber ID.
subscriberStatus: Indicates whether the subscriber is new or existing. Possible values are "new" and "existing".

Example:

{
  "detail": {
    "type": "complete",
    "shopId": 12345,
    "formId": "abc123",
    "origin": "https://example.com/pages/quiz",
    "subscriberId": 67890,
    "subscriberStatus": "new"
  }
}

Subscriber State on Initial Load

When a returning subscriber's ps_id cookie is already present, the embedded form may immediately route them to a completed state without requiring them to fill out the form again.

In this case, the complete event may fire immediately when the form loads.

Multiple Fires

The complete event can fire multiple times if a customer re-enters the final step in a multi-step flow. If your integration should only run once, you should deduplicate the event in your event handler.

let completed = false;

window.addEventListener("postscript:embedded-form", function(ev) {
    if (ev.detail.type !== 'complete' || completed) {
        return;
    }

    completed = true;

    unlockExclusiveContent();
});

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);
    }
});

Track Embedded Form Impression

window.addEventListener("postscript:embedded-form", function(ev) {
    if (ev.detail.type === 'impression') {
        analytics.track('Embedded Form Viewed', {
            form_id: ev.detail.formId
        });
    }
});

Unlock Content After Embedded Form Completion

window.addEventListener("postscript:embedded-form", function(ev) {
    if (ev.detail.type !== 'complete') {
        return;
    }

    if (ev.detail.subscriberStatus === 'new') {
        showQuizResults();
        trackConversion('new-subscriber', ev.detail.subscriberId);
    } else {
        showQuizResults();
    }
});

Track Embedded Form Step Changes

window.addEventListener("postscript:embedded-form", function(ev) {
    if (ev.detail.type !== 'step-change') {
        return;
    }

    analytics.track('Embedded Form Step Reached', {
        form_id: ev.detail.formId,
        from_step: ev.detail.previousStepName,
        to_step: ev.detail.stepName
    });
});

Postscript Ready (postscriptReady)

Popup Events (postscriptPopup)

Impression (impression)

Event Details Structure

Example:

Form Submission (formSubmit)

Event Details Structure

Example:

Close (close)

Event Details Structure

Example:

Subscriber Created (subscriberCreated)

Event Details Structure

Embedded Form Events (postscript:embedded-form)

Mount (mount)

Event Details Structure

Example:

Impression (impression)

Event Details Structure

Example:

Step Change (step-change)

Event Details Structure

Example:

Complete (complete)

Event Details Structure

Example:

Subscriber State on Initial Load

Multiple Fires

Use Cases

Postscript Ready Event

Track Popup Impression to Google Tag Manager

Track Form Submission to Google Tag Manager

Track Popup Close to Google Tag Manager

Track Subscriber Creation to Google Tag Manager

Track Embedded Form Impression

Unlock Content After Embedded Form Completion

Track Embedded Form Step Changes

Postscript Ready (`postscriptReady`)

Popup Events (`postscriptPopup`)

Impression (`impression`)

Form Submission (`formSubmit`)

Close (`close`)

Subscriber Created (`subscriberCreated`)

Embedded Form Events (`postscript:embedded-form`)

Mount (`mount`)

Impression (`impression`)

Step Change (`step-change`)

Complete (`complete`)