> For the complete documentation index, see [llms.txt](https://documentation.pushly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.pushly.com/integration/web-push/sdk/methods.md).

# SDK Methods

## Manually Triggering the Opt-In Prompt

You may choose to disable automatic triggering of the opt-in prompt via the platform. In this scenario you would choose to trigger the prompt based on your own criteria (eg: after a visitor clicks a specific link, visits a specific page, etc).

Triggering the prompt is as easy as calling the `show_prompt` event when a visitor performs the desired action.

```javascript
pushly('show_prompt', { checkEligibility: true })
```

If you want the prompt to show regardless of current subscription status or frequency capping (i.e., manually displaying a bell or custom prompt) this can be simplified to the following code.

```javascript
pushly('show_prompt')
```

## Adding Attributes to a Subscriber's Profile

You can add attributes to a subscriber's profile and later perform segmentation based on those attributes. For example, you may want to tag visitors who are interested in a specific type of news (eg: politics, sports) so that you can target them with specific notifications.

```javascript
pushly('profile', {
  'is_paying_subscriber': true,
  'interests': ['poltics', 'news']
});
```

{% hint style="info" %}
Property values can be scalar or an array of scalar values.
{% endhint %}

If you're storing the value of a property as an array you can use the `profile_append` and `profile_remove` methods to add or remove values.

```javascript
// add 'sports' to the subscriber's interests
pushly('profile_append', {
  'interests': ['sports']
});

// remove 'fashion' and 'news' from the subscriber's interests
pushly('profile_remove', {
  'interests': ['fashion', 'news']
});
```

{% hint style="warning" %}
Properties using `profile_append` will only store the most recent 20 values provided.
{% endhint %}

## Adding Page Keywords / Tags to a Subscriber's Profile

You can add page keywords / tags to a subscribers profile for every page they visit. These tags can then be used in segmentation to create cohorts of subscribers that have visited tags based on number of times and recency. For example: "Subscribers who have visited a page tagged with "Astrology" at least 4 times in the last 30 days".

```javascript
pushly('page_tag_visit', ['Tag1', 'Tag2', 'Tag3']);
```

## Retrieving the Subscriber's User ID

{% hint style="warning" %}
This method is only available after the SDK is fully loaded. This SDK method should be wrapped inside of the `on_ready` event.
{% endhint %}

Run the following code to the get the user's Pushly ID. This is a transient ID that may change often so it should not be used for long-term visitor identification.

```javascript
pushly('on_ready', function() {
    PushlySDK.getUser().getId();
});
```

## Setting the Subscriber's External ID

Providing a unique User ID for your subscriber allows you to later interact with that subscriber via the API.

There are two ways to provide the external ID:

#### On SDK Init

Preferably you may provide the external ID when the SDK is initialized. This requires adding one additional line of code to the `load` function. Note the new `externalId` line in the below script:

```javascript
<script src="https://cdn.p-n.io/pushly-sdk.min.js?domain_key=DOMAIN_KEY" async></script>
<script>
  var PushlySDK = window.PushlySDK || [];
  function pushly() { PushlySDK.push(arguments) }
  pushly('load', {
    domainKey: 'DOMAIN_KEY',
    externalId: 'REPLACE_WITH_USER_ID'
  });
</script>
```

#### Via a separate method call

Alternatively you may provide the external ID any time after the SDK has loaded via the following code:

```javascript
pushly('external_id', 'h7bwKwuE3');
```

Once a subscriber's external ID has been set you may work with our team to set up bi-directional automated data syncs. The following use cases are common ways that publishers use the external ID via server-to-server requests:

* Sending notifications to individual subscribers programmatically
* Processing unsubscribe requests
* Adding and removing profile attributes and events to subscribers

{% hint style="info" %}
While a visitor is opted out (see [Opting a Visitor Out](#opting-a-visitor-out)), the SDK does not store an external ID in that browser, whether it is passed to `load` or set with `external_id`. The same applies on a page where consent is `pending` or `denied` (see [Consent & Privacy](/integration/web-push/sdk/consent-and-privacy.md)).
{% endhint %}

## Removing a Subscriber's External ID

If you want to disassociate an External ID from a subscriber run the following javascript:

```javascript
pushly('deregister_external_id');
```

## Determining if a Visitor is Already Subscribed

{% hint style="warning" %}
This method is only available after the SDK is fully loaded. This SDK method should be wrapped inside of the `on_ready` event.
{% endhint %}

If you need to know if a visitor is already subscribed to push notifications the following javascript can be used:

```javascript
pushly('on_ready', function() {
    await PushlySDK.isUserSubscribed();
});
```

The result of this call will be a boolean `true` or `false` representing the subscription status of the visitor. It is always `false` for a visitor who has opted out or whose data was deleted in this browser. It is also `false` on a page where consent is `pending` or `denied`, even for an existing subscriber, because the SDK does not read the subscription until consent is granted.

{% hint style="info" %}
Note the use of the `on_ready` event to ensure that the SDK is ready for interaction.
{% endhint %}

## Determining if a Visitor is Eligible to Prompt

{% hint style="warning" %}
This method is only available after the SDK is fully loaded. This SDK method should be wrapped inside of the `on_ready` event.
{% endhint %}

If you need to determine if the visitor meets all requirements to be prompted for push permission run the following JavaScript:

```javascript
pushly('on_ready', function() {
    await PushlySDK.isUserEligibleToPrompt();
});
```

The result of this call will be a boolean `true` or `false` representing if the visitor is eligible to be shown a permission dialog.

{% hint style="info" %}
Note the use of the `on_ready` event to ensure that the SDK is ready for interaction.
{% endhint %}

## Suppressing & Allowing Prompts

If you use automatic prompting but need to temporarily block prompts at runtime — for example while a checkout, paywall, or other modal flow is active — you can suppress prompting on demand and re-enable it afterward. Automatic prompting stays configured as normal; suppression only pauses it at runtime.

Suppress prompting when your flow begins (eg: a checkout modal opens):

```javascript
pushly('suppress_prompts')
```

Allow prompting again when the flow ends (eg: the modal closes or completes):

```javascript
pushly('allow_prompts')
```

To check whether prompting is currently suppressed:

```javascript
pushly('get_prompting_suppressed_state', (isSuppressed) => { ... })
```

While suppressed, no prompt is shown — neither automatic prompts nor a manual `show_prompt` call. A prompt already on screen when you call `suppress_prompts` is taken down, and is not recorded as dismissed. A browser's own permission dialog cannot be closed by a website, so one already showing stays until the visitor answers it.

{% hint style="info" %}
The suppressed state is held in memory. It persists across single-page-app (SPA) navigation and is cleared automatically on a full page reload, so a missed `allow_prompts` call cannot leave a visitor permanently unable to be prompted.
{% endhint %}

When you call `allow_prompts`, if the prompt's configured display delay has already elapsed the eligible prompt appears shortly after; otherwise it appears once the delay is met. Time spent suppressed still counts toward the delay.

When the SDK stops running on a page — for example on a browser without web push support, or for a visitor who has opted out — prompting is suppressed for the rest of that page, and `get_prompting_suppressed_state` reports `true`.

{% hint style="warning" %}
`suppress_prompts` / `allow_prompts` are not the same as `pause_notifications` / `resume_notifications`. Prompt suppression controls whether the opt-in **prompt** is shown; pausing notifications is a soft unsubscribe that controls push **delivery** for a visitor who is already subscribed.
{% endhint %}

## Reporting Consent

If your site uses a consent management platform (CMP), report the visitor's consent with the `consent` option in `load` and the `consent` command. See [Consent & Privacy](/integration/web-push/sdk/consent-and-privacy.md) for how each value behaves, recipes for common consent platforms, and how the SDK's privacy controls compare.

```javascript
pushly('consent', 'granted'); // 'pending', 'granted' or 'denied'
```

## Pausing / Resuming a User's Notifications (Soft Unsubscribe)

A user's notifications can be paused by calling the following method:

```javascript
pushly('pause_notifications')
```

If the user's notifications should be resumed call the following method:

```javascript
pushly('resume_notifications')
```

To check if the user's notifications are currently paused:

```javascript
pushly('get_notifications_paused_state', (isPaused) => { ... })
```

{% hint style="info" %}
Pausing only stops delivery; the SDK keeps tracking the visitor. To withdraw a visitor's consent to notifications and tracking, use [`opt_out`](#opting-a-visitor-out) instead.
{% endhint %}

## Opting a Visitor Out

When a visitor withdraws consent to push notifications and tracking, call `opt_out`:

```javascript
pushly('opt_out')
```

Or, from the object API:

```javascript
pushly('on_ready', function() {
    await PushlySDK.UserProfile.optOut()
});
```

Opting out:

* removes the visitor's push subscription in this browser, so no further notifications arrive, and closes any notifications already on screen;
* stops all SDK tracking and prompts in this browser;
* removes the visitor's external ID from this browser;
* tells Pushly, which marks the subscriber as unsubscribed and removes them from active campaigns and scheduled sends.

If the opt-out cannot reach Pushly straight away (for example, the visitor is offline), the SDK keeps it and sends it again on the visitor's next page load.

The opt-out lasts until the visitor opts back in or clears this site's data in their browser. It applies to every page of your site that shares the SDK's storage, including event-only subdomains. Reporting `consent: 'granted'` later does not undo it.

{% hint style="info" %}
Opt-out applies to the current browser only. If a visitor uses several browsers, call `opt_out` in each one where they withdraw consent.
{% endhint %}

## Opting a Visitor Back In

If a visitor who opted out wants notifications again, call `opt_in`:

```javascript
pushly('opt_in')
```

Or, from the object API:

```javascript
pushly('on_ready', function() {
    await PushlySDK.UserProfile.optIn()
});
```

Opting in takes effect on the visitor's **next page load**, so reload the page after calling it (or let the next navigation happen). If the browser still allows notifications for your site, the visitor is subscribed again automatically; otherwise your prompts show as configured.

{% hint style="info" %}
`opt_in` reverses an opt-out only — it does not undo `request_user_deletion`. If your site uses external IDs, set the visitor's external ID again after they opt back in: opting out removes it from the browser.
{% endhint %}

## Deleting a Visitor's Data

When a visitor asks for their data to be deleted, call `request_user_deletion` in their browser:

```javascript
pushly('request_user_deletion');
```

The SDK first stops everything in this browser: it removes the push subscription, closes any notifications on screen, and stops all tracking and prompts. It then sends the deletion request to Pushly.

Pushly erases the data it holds for this visitor on your domain — their profile, their subscription, and the identifiers linked to this browser. Erasure is permanent. If the visitor subscribes again later, they start as a new subscriber with no connection to the erased data.

{% hint style="info" %}
A deletion can also be requested with a link: see [Deletion Links](/integration/web-push/sdk/consent-and-privacy.md#deletion-links).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.pushly.com/integration/web-push/sdk/methods.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.