If you haven't already, sign up for a free account on onesignal.com.

If this is not your first app with OneSignal, click New App/Website. Otherwise, you will see the next page.

Name your app and organization something recognizable, then select Web from the platform list. You can set up more platforms later within the app's Settings page.

Click Next: Configure Your Platform.

1. Choose Integration

1. Choose Integration

Select Typical Site. This will enable you to configure the prompts and other settings directly within the OneSignal dashboard.

2. Site Setup

2. Site Setup

Input your default site information.

Image showing Site Setup step

FieldDescriptionSITE NAMEThe default name for your site. Shows in push notifications.SITE URLYour actual website URL (e.g. https://example.com, https://www.example.com).
Must include:
- https://
- If your site uses www make sure to include it.

To test locally, see Local Testing Setup.AUTO RESUBSCRIBE (HTTPS ONLY)Recommended: Allows push subscribers to automatically resubscribe upon returning to your site without being prompted if they clear their browser data or if you are transferring to OneSignal from another push provider.DEFAULT ICON URLIcon used for Prompting and the default for push notifications.

Enter an https icon URL or upload file that is square 256x256 pixels.

The file must be .png, .jpg, or .gif.

3. Permission Prompt Setup

3. Permission Prompt Setup

By default, the Push Slide Prompt will show on the first page view after 10 seconds. You can skip this step for now and come back later to add new prompts or modify this one. See our Web Prompting Guide for more details.

4. Welcome Notification (Optional)

4. Welcome Notification (Optional)

A push notification sent immediately to current user upon subscribing to your site for the first time. Enabled by default, it can be toggled off to prevent showing and update message content at anytime. If you want to add a delay, toggle off this notification and use Journeys or Automated Messages.

5. Advanced Push Settings (Optional)

5. Advanced Push Settings (Optional)

OneSignal provides several Advanced Options. For instance:

Multiple Service Workers

Multiple Service Workers

If you are using or plan to use another service worker on your site, please follow the OneSignal Service Worker Setup Guide.

Safari Certificate (Optional)

Safari Certificate (Optional)

OneSignal automatically provides the necessary certificates to work with Safari Browsers at no additional cost. If you already have your own Safari Web Push Certificates, toggle on this option to upload your Safari Web .p12 Push Certificate and password.

Click Save to continue.

6. Upload Files

6. Upload Files

Download OneSignal SDK file which is the Service Worker file. You must upload this file to your server.

Option 1. Create file and copy code

Option 1. Create file and copy code

1. Create a new file OneSignalSDKWorker.js and make it public.

2. Copy-paste the following import statement into the file:

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

Option 2. Download zip folder and upload

Option 2. Download zip folder and upload

1. Click Download OneSignal SDK files (you can also download the file here).

2. Unzip the download. There should be a single file you need to host.

Hosting the file

Hosting the file

The OneSignal SDK file must be publicly accessible and can be placed at the top-level root of your site. The OneSignal SDK will look for the file at https://yoursite.com/OneSignalSDKWorker.js. If you want to place them in a subfolder, you can! Please see our OneSignal Service Worker Guide for instructions.

📘

Subfolders or Migrating from another Push Provider

If you want to place the OneSignalSDKWorker.js file in a subfolder or if you are migrating to OneSignal from another provider, please see our OneSignal Service Worker Guide for instructions.

🚧

Note regarding Service Worker file(s)

If you are revisiting this page for an existing site set up prior to November 22, 2021 and are currently using two service worker files:

• OneSignalSDKWorker.js
• OneSignalSDKUpdaterWorker.js

you should continue hosting both files. This is to prevent the Service Worker from going stale if a user doesn't return to your site in some time.

On November 22, 2021 the OneSignal Web SDK was updated to require only a single service worker file. New setups will now only require a single file.

7. Add Code to Site

7. Add Code to Site

To enable OneSignal on your site, you will need to paste the provided code into your website's <head>. If you do not have access to modify your site's code, you will need to contact a developer to help you.

The OneSignal JavaScript SDK code should work on any site, but if your site is setup using Angular, React JS, or Vue JS then follow these links.

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.init({
      appId: "YOUR_ONESIGNAL_APP_ID",
    });
  });
</script>

8. Subscribe and Send Yourself a Notification

Go to your website. You should be prompted to subscribe to push notifications based on the prompt settings you setup. Click it to see the native browser prompt and subscribe to push. Then, Find & Set Test Subscriptions and send yourself a Push Notification.

👍

Setup Complete!

If you are having difficulty, please check Web Push Troubleshooting or contact [email protected] for assistance.

📘

OneSignal's Hiring!

If you love OneSignal and would like to work here, let us know! Feel free to browse our open positions and apply on our careers page: https://onesignal.com/careers

The Create Notification method is used when you want your server to programmatically send Push Notification, Email, and SMS messages through OneSignal. You may target users in one of three ways using this method:

🚧

You may only use one method of targeting users

If a targeting parameter of one type is used, then targeting parameters from other types may not be used. For instance, you cannot use the include_aliases parameter with filters. You must use one or the other.

Send to Segments

Send to Segments

Segments are the most common way to target large groups of devices. Sending to segments is easy: you simply specify which segments you want to target and, optionally, which ones you don't.

ParameterTypeDescriptionincluded_segmentsarray_stringThe segment names you want to target. Users in these segments will receive a notification. This targeting parameter is only compatible with excluded_segments.

Example: ["Active Users", "Inactive Users"]excluded_segmentsarray_stringSegment that will be excluded when sending. Users in these segments will not receive a notification, even if they were included in included_segments. This targeting parameter is only compatible with included_segments.

Example: ["Active Users", "Inactive Users"]

Send to Users Based on Filters

Send to Users Based on Filters

Filters work the same as segments without needing to create the segment first. Filters can be combined to form advanced, highly precise user targeting.

The filters parameter targets notification recipients using an array of JSON objects containing field conditions to check. The following are filter field options:

fieldDescriptionlast_sessionrelation = ">" or "<"
hours_ago = number of hours before or after the users last session. Example: "1.1"first_sessionrelation = ">" or "<"
hours_ago = number of hours before or after the users first session. Example: "1.1"session_countrelation = ">", "<", "=" or "!="
value = number sessions. Example: "1"session_timerelation = ">" or "<"
value = Time in seconds the user has been in your app. Example: "3600"amount_spentrelation = ">", "<", or "="
value = Amount in USD a user has spent on IAP (In App Purchases). Example: "0.99"bought_skurelation = ">", "<" or "="
key = SKU purchased in your app as an IAP (In App Purchases). Example: "com.domain.100coinpack"
value = value of SKU to compare to. Example: "0.99"tagrelation = ">", "<", "=", "!=", "exists", "not_exists", "time_elapsed_gt" (paid plan only) or "time_elapsed_lt" (paid plan only)
See Time Operators

key = Tag key to compare.
value = Tag value to compare. Not required for "exists" or "not_exists". Example: See Formatting Filters

Do not use tags for targeting individual users via a "user id". Instead use external_id or custom alias and the include_aliases targeting property.languagerelation = "=" or "!="
value = 2 character language code. Example: "en". For a list of all language codes see Language & Localization.app_versionrelation = ">", "<", "=" or "!="
value = app version. Example: "1.0.0"locationradius = in meters
lat = latitude
long = longitudecountryrelation = "="
value = 2-digit Country code
Example: "field": "country", "relation": "=", "value": "US"

Filter Usage

Filter Usage

• Filter entries use "AND" by default; insert {"operator": "OR"} between entries to "OR" the parameters together.
• "AND" has priority over "OR".
• For performance reasons, a maximum of 200 entries can be used at a time. The 200 entries limit includes the "field" entry and "OR" entries -- each would count towards the 200 limit. Below, "Formatting Example 1" would be 2 entries and "Formatting Example 2" would be 3 entries.
• Tag filters using an equality ("=") or "exists" operator are very fast.
• Negation (eg. "!=" and "not_exists") is inherently more expensive to compute. Our default database indices map tags to devices, and can’t track which devices don’t have specific tags -- there are infinite tag keys which each device does not have. Upon request, it is sometimes possible for us to create a specific index on your application to address problems with negation.
• Numeric ordering operator like "<" or ">" are slow by default. Note that upon special request, we can add a special index for specific tags to improve performance of these operators.
• Filters on the "last_session", "session_count", and "country" fields are fast on their own or together, but when used with other filters such as tags can make the segment take longer to compute.

🚧

You may only use one method of targeting users

filters cannot be combined with included_segments, include_aliases and other device targeting options in the same request.

Formatting Filters

Formatting Filters

The power of filters comes from combining several fields and operators to precisely target your users. The following are examples of filters and how to format them:

1. A user is level 10 and purchased an item

2. A user is level 10 or 20

3. A user is not VIP or is admin

4. User's tags include key username and the user is not banned.

5. A user is in country US and on level 10 or country ES and on level 10

"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"field": "amount_spent", "relation": ">","value": "0"}
]

"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"}, 
  {"operator": "OR"}, {"field": "tag", "key": "level", "relation": "=", "value": "20"}
]

"filters": [
  {"field": "tag", "key": "is_vip", "relation": "!=", "value": "true"},
  {"operator": "OR"}, {"field": "tag","key": "is_admin", "relation": "=", "value": "true"}
]

"filters": [
  {"field": "tag", "key": "username", "relation": "exists"},
  {"field": "tag", "key": "banned", "relation": "!=", "value": "true"}
]

"filters": [
  { "field": "tag", "key": "country", "relation": "=", "value": "US" },
  { "field": "tag", "key": "level", "relation": "=", "value": "10" },
  { "operator": "OR" },
  { "field": "tag", "key": "country", "relation": "=", "value": "ES" },
  { "field": "tag", "key": "level", "relation": "=", "value": "10" }
]

Send to Specific Users and Subscriptions

Send to Specific Users and Subscriptions

You may also target specific users and their associated devices. This is typically used in two ways:

1. For transactional notifications that target individual users.

2. For apps that wish to manage their own user-groups, such as tracking a user's followers and sending notifications to them when that user posts.

When targeting specific devices, you may use any of the following parameters together:

🚧

You may only use one method of targeting users

Targeting specific devices cannot be combined with included_segments, filters and other device targeting options in the same request.

ParameterTypeDescriptioninclude_aliasesobjectRecommended for transactional messages
Target specific users by aliases assigned via API. An alias can be an external_id, onesignal_id, or a custom alias.

Example: { "external_id": ["custom-external_id-assigned-by-api"]}

REQUIRED: REST API Key Authentication

Limit of 2,000 entries per REST API call.

Note: Use with target_channel to indicate you are sending a "push" or "email" or "sms".DEPRECATING:: include_external_user_idsarray_stringDEPRECATING: Use include_aliases with external_id and target_channel instead.

Target specific devices by custom user IDs assigned via API.

Example: [“custom-id-assigned-by-api”]
REQUIRED: REST API Key Authentication

Limit of 2,000 entries per REST API call.

Note: If targeting push, email, or sms subscribers with same ids, use with channel_for_external_user_ids to indicate you are sending a "push" or "email" or "sms".include_subscription_ids

DEPRECATING:
include_player_idsarray_stringTarget the specific subscription IDs. It is recommended to use include_aliases with external_id instead to send to all subscriptions belonging to a single user.

Does not require API Auth Key.

Example: ["1dd608f2-c6a1-11e3-851d-000c2940e62c"]

Limit of 2,000 entries per REST API callinclude_email_tokensarray_stringRecommended for Sending Emails - Target specific email addresses.

If an email does not correspond to an existing user, a new user will be created.

Example: [email protected]

Limit of 2,000 entries per REST API callinclude_phone_numbersarray_stringRecommended for Sending SMS - Target specific phone numbers. The phone number should be in the E.164 format. Phone number should be an existing subscriber on OneSignal. Refer our docs to learn how to add phone numbers to OneSignal.

Example phone number: +1999999999

Limit of 2,000 entries per REST API callinclude_ios_tokensarray_stringNot Recommended: Please consider using include_player_ids or include_aliases instead.

Target using iOS device tokens.

Warning: Only works with Production tokens.

All non-alphanumeric characters must be removed from each token. If a token does not correspond to an existing user, a new user will be created.

Example: ce777617da7f548fe7a9ab6febb56cf39fba6d38203...

Limit of 2,000 entries per REST API callinclude_wp_wns_urisarray_stringNot Recommended: Please consider using include_player_ids or include_aliases instead.

Target using Windows URIs. If a token does not correspond to an existing user, a new user will be created.

Example: http://s.notify.live.net/u/1/bn1/HmQAAACPaLDr-...

Limit of 2,000 entries per REST API callinclude_amazon_reg_idsarray_stringNot Recommended: Please consider using include_player_ids or include_aliases instead.

Target using Amazon ADM registration IDs. If a token does not correspond to an existing user, a new user will be created.

Example: amzn1.adm-registration.v1.XpvSSUk0Rc3hTVVV...

Limit of 2,000 entries per REST API callinclude_chrome_reg_idsarray_stringNot Recommended: Please consider using include_player_ids or include_aliases instead.

Target using Chrome App registration IDs. If a token does not correspond to an existing user, a new user will be created.

Example: APA91bEeiUeSukAAUdnw3O2RB45FWlSpgJ7Ji_...

Limit of 2,000 entries per REST API callinclude_chrome_web_reg_idsarray_stringNot Recommended: Please consider using include_player_ids or include_aliases instead.

Target using Chrome Web Push registration IDs. If a token does not correspond to an existing user, a new user will be created.

Example: APA91bEeiUeSukAAUdnw3O2RB45FWlSpgJ7Ji_...

Limit of 2,000 entries per REST API callinclude_android_reg_idsarray_stringNot Recommended: Please consider using include_player_ids or include_aliases instead.

Target using Android device registration IDs. If a token does not correspond to an existing user, a new user will be created.

Example: APA91bEeiUeSukAAUdnw3O2RB45FWlSpgJ7Ji_...

Limit of 2,000 entries per REST API call

Platform to Deliver To

Platform to Deliver To

By default, OneSignal will send to every platform (each platform equals true).

To only send to specific platforms, you may pass in true on one or more of these boolean parameters corresponding to the platform you wish to target. If you do so, all other platforms will be set to false and will not be delivered to.

🚧

Limitation Targeting include_player_ids

These parameters will be ignored if sending to devices directly with include_player_ids

For example, sending push to include_player_ids associated with Android, iOS and Web Platform:

{
  "include_player_ids": ["player_id_1", "player_id_2"],
  "isIos": true
}

This will ignore isIos and send the push message to all subscribed devices with these Player Ids.

🚧

Targeting include_aliases channels

Aliases can be associated with Push, Email, or SMS records. You must set target_channel to "push" or "email" or "sms" when sending to that channel.

For Example, sending email to an external_id associated with a push, email and sms record:

{
  "include_aliases": {
    "external_id": ["external_user_id_on_push_email_sms"]
  },
  "target_channel": "email"
}

If you want to send push to devices on a specific platform, like Android only for example:

{
  "include_aliases": {
    "external_id": ["external_user_id"]
  },
  "target_channel": "push",
  "isAndroid": true
}

ParameterTypePlatformDescriptionisIosbooleaniOSIndicates whether to send to all devices registered under your app's Apple iOS platform.isAndroidbooleanAndroidIndicates whether to send to all devices registered under your app's Google Android platform.isHuaweibooleanHuaweiIndicates whether to send to all devices registered under your app's Huawei Android platform.isAnyWebbooleanAll Browsers

Indicates whether to send to all subscribed web users, including Chrome, Firefox, and Safari.

You may use this instead as a combined flag instead of separately enabling isChromeWeb, isFirefox, and isSafari, though the three options are equivalent to this one.

isChromeWebbooleanChromeIndicates whether to send to all Google Chrome and Mozilla Firefox users registered under your Chrome & Firefox web push platform.isFirefox booleanFirefoxIndicates whether to send to all Mozilla Firefox users registered under your Firefox web push platform.isSafaribooleanSafariIndicates whether to send to all Apple's Safari users registered under your Safari web push platform.isWP_WNSbooleanWindowsIndicates whether to send to all devices registered under your app's Windows platform.isAdmbooleanAmazonIndicates whether to send to all devices registered under your app's Amazon Fire platform.isChromebooleanChromeAppIndicates whether to send to all devices registered under your app's Google Chrome Apps & Extension platform. This flag is not used for web push. Please see isChromeWeb for sending to web push users.target_channelstring"push" or "email" or "sms"Indicates if the message type when targeting with include_aliases for cases where an email, sms, and/or push subscribers have the same external user id.

Example: Use the string "push" to indicate you are sending a push notification or the string "email"for sending emails or "sms"for sending SMS.DEPRECATED channel_for_external_user_ids string"push" or "email" or "sms"DEPRECATED: Use target_channel with include_aliases instead.

Indicates if the message type when targeting with include_external_user_ids for cases where an email, sms, and/or push subscribers have the same external user id.

Example: Use the string "push" to indicate you are sending a push notification or the string "email"for sending emails or "sms"for sending SMS.