OneSignal

https://documentation.onesignal.com/docs/en/
Admin
OneSignal is an omnichannel messaging platform that provides comprehensive tools for sending push...
Tokens:441,068
Snippets:6,427
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example init for Custom Code Setup

Source: https://documentation.onesignal.com/docs/en/web-sdk-reference

Example of initializing the OneSignal SDK with custom code setup, including notifyButton and promptOptions.

```javascript
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "YOUR_APP_ID",
    safari_web_id: "YOUR_SAFARI_WEB_ID",
    notifyButton: {
      enable: true,
    },
    promptOptions: {
      slidedown: {
        prompts: [{
            type: "smsAndEmail",
            autoPrompt: false,
            text: {
              emailLabel: "Insert Email Address",
              smsLabel: "Insert Phone Number",
              acceptButton: "Submit",
              cancelButton: "No Thanks",
              actionMessage: "Receive the latest news, updates and offers as they happen.",
              updateMessage: "Update your push notification subscription preferences.",
              confirmMessage: "Thank You!",
              positiveUpdateButton: "Save Preferences",
              negativeUpdateButton: "Cancel",
            },
            delay: {
              pageViews: 1,
              timeDelay: 20
            },
          },
          {
            type: "category",
            autoPrompt: true,
            text: {
              actionMessage: "We'd like to show you notifications for the latest news and updates.",
              acceptButton: "Allow",
              cancelButton: "Cancel",
              negativeUpdateButton: "Cancel",
              positiveUpdateButton: "Save Preferences",
              updateMessage: "Update your push notification subscription preferences.",
            },
            delay: {
              pageViews: 3,
              timeDelay: 20
            },
            categories: [{
                tag: "politics",
                label: "Politics"
              },
              {
                tag: "local_news",
                label: "Local News"
              },
              {
                tag: "world_news",
                label: "World News",
              },
              {
                tag: "culture",
                label: "Culture"
              },
            ]
          }
        ]
      }
    }
  });
});
</script>
```

--------------------------------

### Setup and Start Default Live Activities

Source: https://documentation.onesignal.com/docs/en/mobile-sdk-reference

Configures cross-platform SDKs to manage Live Activity lifecycles and provides methods to launch activities from within the app.

```csharp
using OneSignalSDK;

//Push To Start
OneSignal.LiveActivities.SetupDefault();

//Launching the Live Activity from within the app (not needed for push to start)
string activityId = "my_activity_id";

OneSignal.LiveActivities.StartDefault(
  activityId,
  new Dictionary<string, object>() {
      { "title", "Welcome!" }
  },
  new Dictionary<string, object>() {
      { "message", new Dictionary<string, object>() {
          { "en", "Hello World!"}
      }},
  });
```

```javascript
import { OneSignal } from 'react-native-onesignal'

//Push To Start
OneSignal.LiveActivities.setupDefault()

//Launching the Live Activity from within the app (not needed for push to start)
const activityId = "my_activity_id"
const attributes = { title: "Sample Title" } ;
const content = { message: { en: "message" } };
OneSignal.LiveActivities.startDefault(activityId, attributes, content);
```

```dart
import 'package:onesignal_flutter/onesignal_flutter.dart';

OneSignal.LiveActivities.setupDefault()

//Launching the Live Activity from within the app (not needed for push to start)
const String activityId = "my_activity_id";
OneSignal.LiveActivities.startDefault(activityId!, {
  "title": "Welcome!"
  }, {
  "message": {"en": "Hello World!"},
});
```

```javascript
//Ionic
import OneSignal from "onesignal-cordova-plugin";

//Push To Start
OneSignal.LiveActivities.setupDefault();

//Launching the Live Activity from within the app (not needed for push to start)
const activityId = "my_activity_id";
const attributes = { title: "Sample Title" };
const content = { message: { en: "message" } };
OneSignal.LiveActivities.startDefault(activityId, attributes, content);

//Cordova
//Push To Start
window.plugins.OneSignal.LiveActivities.setupDefault();

//Launching the Live Activity from within the app (not needed for push to start)
const activityId = "my_activity_id";
const attributes = { title: "Sample Title" };
const content = { message: { en: "message" } };
window.plugins.OneSignal.LiveActivities.startDefault(
  activityId,
  attributes,
  content
);
```

--------------------------------

### Install Go SDK

Source: https://documentation.onesignal.com/docs/en/server-sdk-reference

Use go get to install the OneSignal Go API client.

```bash
go get github.com/OneSignal/onesignal-go-api/v5
```

--------------------------------

### Install Node.js SDK

Source: https://documentation.onesignal.com/docs/en/server-sdk-reference

Use npm to install the OneSignal Node.js package.

```bash
npm install @onesignal/node-onesignal
```

--------------------------------

### Rendered output examples

Source: https://documentation.onesignal.com/docs/en/event-streams-data

Examples of how message data appears for push notifications and email messages.

```json
{
    "message.id": "f3c9cd09-10d7-4f59-b9bc-66e16607f1d5",
    "message.name": "weekly-promo-push",
    "message.title": "{'en':'Flash Sale: 50% Off Today'}",
    "message.contents": "{'en':'Shop now and save on select items'}",
    "message.template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message.url": "https://example.com/sale",
    "message.app_url": "",
    "message.web_url": "",
    "message.data": "{'url': 'https://example.com/sale'}",
    "message.custom_data": "{}"
  }
```

```json
{
    "message.id": "e2d3c4b5-a6f7-8901-bcde-f12345678901",
    "message.name": "onboarding-welcome-email",
    "message.title": "Welcome to Acme: here's how to get started",
    "message.contents": "",
    "message.template_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "message.url": "",
    "message.app_url": "",
    "message.web_url": "",
    "message.data": "{}",
    "message.custom_data": "{}"
  }
```

--------------------------------

### Start a Live Notification

Source: https://documentation.onesignal.com/docs/en/android-live-notifications

Initialize a live notification by sending a start event with initial static and dynamic data.

```bash
curl -X POST "https://api.onesignal.com/notifications" \
  -H "Authorization: Key YOUR_APP_API_KEY" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "isAndroid": true,
    "collapse_id": "UNIQUE_LIVE_NOTIFICATION_ID",
    "data": {
      "live_notification": {
        "key": "progress",
        "event": "start",
        "event_attributes": {},
        "event_updates": {
          "current_progress": 0
        }
      }
    },
    "headings": { "en": "Start" },
    "contents": { "en": "Starting Live Notification" },
    "include_subscription_ids": ["YOUR_SUBSCRIPTION_ID"],
    "target_channel": "push"
  }'
```

--------------------------------

### Initialize OneSignal SDK with Custom Code Setup

Source: https://documentation.onesignal.com/docs/en/web-sdk-reference

This example demonstrates initializing the OneSignal SDK with custom prompt options, including slidedown prompts for SMS/Email and category-based notifications. Ensure you replace 'YOUR_APP_ID' and 'YOUR_SAFARI_WEB_ID' with your actual OneSignal credentials.

```javascript
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "YOUR_APP_ID",
    safari_web_id: "YOUR_SAFARI_WEB_ID",
    notifyButton: {
      enable: true,
    },
    promptOptions: {
      slidedown: {
        prompts: [{
            type: "smsAndEmail",
            autoPrompt: false,
            text: {
              emailLabel: "Insert Email Address",
              smsLabel: "Insert Phone Number",
              acceptButton: "Submit",
              cancelButton: "No Thanks",
              actionMessage: "Receive the latest news, updates and offers as they happen.",
              updateMessage: "Update your push notification subscription preferences.",
              confirmMessage: "Thank You!",
              positiveUpdateButton: "Save Preferences",
              negativeUpdateButton: "Cancel",
            },
            delay: {
              pageViews: 1,
              timeDelay: 20
            },
          },
          {
            type: "category",
            autoPrompt: true,
            text: {
              actionMessage: "We'd like to show you notifications for the latest news and updates.",
              acceptButton: "Allow",
              cancelButton: "Cancel",

              /* CATEGORY SLIDEDOWN SPECIFIC TEXT */
              negativeUpdateButton: "Cancel",
              positiveUpdateButton: "Save Preferences",
              updateMessage: "Update your push notification subscription preferences.",
            },
            delay: {
              pageViews: 3,
              timeDelay: 20
            },
            categories: [{
                tag: "politics",
                label: "Politics"
              },
              {
                  tag: "local_news",
                  label: "Local News"
                },
                {
                  tag: "world_news",
                  label: "World News",
                },
                {
                  tag: "culture",
                  label: "Culture"
                },
              ]
            }
          ]
        }
      }
    }
  });
});
</script>
```

--------------------------------

### Install OneSignal SDK

Source: https://documentation.onesignal.com/docs/en/react-native-sdk-setup

Command to resolve missing module errors by installing the package.

```bash
npm install react-native-onesignal
```

--------------------------------

### POST /notifications (Start)

Source: https://documentation.onesignal.com/docs/en/android-live-notifications

Initializes a Live Notification by sending an event with type 'start'. This sets up the initial static and dynamic data for the notification.

```APIDOC
## POST /notifications

### Description
Initializes a new Live Notification instance on the target Android device.

### Method
POST

### Endpoint
https://api.onesignal.com/notifications

### Request Body
- **app_id** (string) - Required - Your OneSignal App ID
- **isAndroid** (boolean) - Required - Must be true for Android delivery
- **collapse_id** (string) - Required - Unique ID for the Live Notification instance
- **data** (object) - Required - Contains the live_notification object with event 'start'
- **headings** (object) - Required - Notification title
- **contents** (object) - Required - Notification body
- **include_subscription_ids** (array) - Required - List of target subscription IDs

### Request Example
{
  "app_id": "YOUR_APP_ID",
  "isAndroid": true,
  "collapse_id": "UNIQUE_LIVE_NOTIFICATION_ID",
  "data": {
    "live_notification": {
      "key": "progress",
      "event": "start",
      "event_attributes": {},
      "event_updates": {
        "current_progress": 0
      }
    }
  },
  "headings": { "en": "Start" },
  "contents": { "en": "Starting Live Notification" },
  "include_subscription_ids": ["YOUR_SUBSCRIPTION_ID"],
  "target_channel": "push"
}
```

--------------------------------

### Manage Push To Start Tokens

Source: https://documentation.onesignal.com/docs/en/cross-platform-live-activity-setup

Methods for setting and removing Push To Start tokens for Live Activities. These are optional low-level methods for custom token management.

```javascript
//Setting the Push To Start Token
OneSignal.LiveActivities.setPushToStartToken(activityType: string, token: string)

//Removing the Push To Start Token
OneSignal.LiveActivities.removePushToStartToken(activityType: string)
```

```csharp
//Setting the Push To Start Token
OneSignal.LiveActivities.SetPushToStartToken(string activityType, string token)

//Removing the Push To Start Token
OneSignal.LiveActivities.RemovePushToStartToken(string activityType)
```

```javascript
/* Cordova */
//Setting the Push To Start Token
window.plugins.OneSignal.LiveActivities.setPushToStartToken(activityType: string, token: string)

//Removing the Push To Start Token
window.plugins.OneSignal.LiveActivities.removePushToStartToken(activityType: string)

/* Ionic */
//Setting the Push To Start Token
OneSignal.LiveActivities.setPushToStartToken(activityType: string, token: string)

//Removing the Push To Start Token
OneSignal.LiveActivities.removePushToStartToken(activityType: string)
```

```csharp
//Setting the Push To Start Token
OneSignal.LiveActivities.SetPushToStartToken(string activityType, string token)

//Removing the Push To Start Token
OneSignal.LiveActivities.RemovePushToStartToken(string activityType)
```

```javascript
//Setting the Push To Start Token
OneSignal.LiveActivities.setPushToStartToken(String activityType, String token)

//Removing the Push To Start Token
OneSignal.LiveActivities.removePushToStartToken(String activityType)
```

--------------------------------

### Install C# (.NET) SDK

Source: https://documentation.onesignal.com/docs/en/server-sdk-reference

Use the dotnet CLI to add the OneSignalApi package.

```bash
dotnet add package OneSignalApi
```

--------------------------------

### Install iOS Dependencies

Source: https://documentation.onesignal.com/docs/en/cordova-sdk-setup

Run these commands in your terminal to install the updated Podfile dependencies.

```shell
cd ios pod install cd .. 
```

--------------------------------

### Install Python SDK

Source: https://documentation.onesignal.com/docs/en/server-sdk-reference

Use pip to install the OneSignal Python package. Requires Python 3.6+.

```bash
pip install onesignal-python-api
```

--------------------------------

### Custom Event Payload Example

Source: https://documentation.onesignal.com/docs/en/mobile-sdk-reference

Example of the automatically included os_sdk data within a custom event payload.

```json
{
  "os_sdk": {
    "sdk": "050213",
    "device_os": "18.5",
    "type": "iOSPush",
    "device_model": "iPhone14,4",
    "device_type": "ios",
    "app_version": "5.4.0"
  }
}
```

--------------------------------

### Complete HTML in-app message button example

Source: https://documentation.onesignal.com/docs/en/in-app-message-api

A full example showing both the HTML button element and the associated JavaScript event listener.

```html
<button id="buy-now-button" data-onesignal-unique-label="buy-now-button-for-onesignal">
  Buy Now
</button>
<script>
  document.getElementById("buy-now-button").addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { coupon: "10OFF" });
  });
</script>
```

--------------------------------

### Install Ruby SDK

Source: https://documentation.onesignal.com/docs/en/server-sdk-reference

Add the OneSignal gem to your Gemfile.

```ruby
gem 'onesignal', '~> 5.8.0'
```

--------------------------------

### Enter Live Activity

Source: https://documentation.onesignal.com/docs/en/device-user-model-mobile-sdk-mapping

Starts tracking a live activity with a specific token.

```swift
OneSignal.enterLiveActivity("my_activity_id", withToken: myToken)
```

```swift
OneSignal.LiveActivities.enter("my_activity_id", withToken: "TOKEN")
```

--------------------------------

### Install OneSignal Capacitor Plugin

Source: https://documentation.onesignal.com/docs/en/capacitor-sdk-setup

Add the plugin to your project and synchronize native dependencies.

```shell
npm install @onesignal/capacitor-plugin
npx cap sync
```

--------------------------------

### Install Rust SDK

Source: https://documentation.onesignal.com/docs/en/server-sdk-reference

Add the OneSignal crate to your Cargo.toml dependencies.

```toml
onesignal-rust-api = "5.8.0"
```

--------------------------------

### Start Node.js Server

Source: https://documentation.onesignal.com/docs/en/identity-verification

Command to run the local server for testing JWT generation.

```typescript
node server.js
```

--------------------------------

### Configure Live Activity Lifecycle

Source: https://documentation.onesignal.com/docs/en/cross-platform-live-activity-setup

Use setupDefault to manage the LiveActivity lifecycle for DefaultLiveActivityAttributes. In-app initiation is optional and not required for push-to-start workflows.

```javascript
import { OneSignal } from 'react-native-onesignal'

//Push To Start
OneSignal.LiveActivities.setupDefault()

//Launching the Live Activity from within the app (not needed for push to start)
const activityId = "my_activity_id"
const attributes = { title: "Sample Title" } ;
const content = { message: { en: "message" } };
OneSignal.LiveActivities.startDefault(activityId, attributes, content);
```

```csharp
using OneSignalSDK;

//Push To Start
OneSignal.LiveActivities.SetupDefault();

//Launching the Live Activity from within the app (not needed for push to start)
string activityId = "my_activity_id";

OneSignal.LiveActivities.StartDefault(
  activityId,
  new Dictionary<string, object>() {
      { "title", "Welcome!" }
  },
  new Dictionary<string, object>() {
      { "message", new Dictionary<string, object>() {
          { "en", "Hello World!"}
      }},
  });
```

```javascript
/*Cordova*/

//Push To Start
window.plugins.OneSignal.LiveActivities.setupDefault();

//Launching the Live Activity from within the app (not needed for push to start)
const activityId = "my_activity_id";
const attributes = { title: "Sample Title" };
const content = { message: { en: "message" } };
window.plugins.OneSignal.LiveActivities.startDefault(
  activityId,
  attributes,
  content
);

/*Ionic/Capacitor*/
import OneSignal from "onesignal-cordova-plugin";

//Push To Start
OneSignal.LiveActivities.setupDefault();

//Launching the Live Activity from within the app (not needed for push to start)
const activityId = "my_activity_id";
const attributes = { title: "Sample Title" };
const content = { message: { en: "message" } };
OneSignal.LiveActivities.startDefault(activityId, attributes, content);
```

```csharp
using OneSignalSDK;

//Push To Start
OneSignal.LiveActivities.SetupDefault();

//Launching the Live Activity from within the app (not needed for push to start)
string activityId = "my_activity_id";

OneSignal.LiveActivities.StartDefault(
  activityId,
  new Dictionary<string, object>() {
      { "title", "Welcome!" }
  },
  new Dictionary<string, object>() {
      { "message", new Dictionary<string, object>() {
          { "en", "Hello World!"}
      }},
  });
```

```dart
import 'package:onesignal_flutter/onesignal_flutter.dart';

OneSignal.LiveActivities.setupDefault()

//Launching the Live Activity from within the app (not needed for push to start)
const String activityId = "my_activity_id";
OneSignal.LiveActivities.startDefault(activityId!, {
  "title": "Welcome!"
  }, {
  "message": {"en": "Hello World!"},
});
```

--------------------------------

### Initialize OneSignal SDKs

Source: https://documentation.onesignal.com/docs/en/server-sdk-reference

Examples for initializing the OneSignal client across various programming languages using environment variables for API keys.

```javascript
const OneSignal = require('@onesignal/node-onesignal');

const configuration = OneSignal.createConfiguration({
  restApiKey: process.env.ONESIGNAL_REST_API_KEY,
  organizationApiKey: process.env.ONESIGNAL_ORGANIZATION_API_KEY,
});

const client = new OneSignal.DefaultApi(configuration);
```

```python
import os
import onesignal
from onesignal.api import default_api

configuration = onesignal.Configuration(
    rest_api_key=os.environ['ONESIGNAL_REST_API_KEY'],
    organization_api_key=os.environ.get('ONESIGNAL_ORGANIZATION_API_KEY'),
)

with onesignal.ApiClient(configuration) as api_client:
    client = default_api.DefaultApi(api_client)
    # Call client.create_notification(...) and other methods here.
```

```java
import com.onesignal.client.ApiClient;
import com.onesignal.client.Configuration;
import com.onesignal.client.auth.HttpBearerAuth;
import com.onesignal.client.api.DefaultApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

HttpBearerAuth restApiAuth = (HttpBearerAuth) defaultClient
    .getAuthentication("rest_api_key");
restApiAuth.setBearerToken(System.getenv("ONESIGNAL_REST_API_KEY"));

HttpBearerAuth orgApiAuth = (HttpBearerAuth) defaultClient
    .getAuthentication("organization_api_key");
orgApiAuth.setBearerToken(System.getenv("ONESIGNAL_ORGANIZATION_API_KEY"));

DefaultApi client = new DefaultApi(defaultClient);
```

```go
import (
    "context"
    "os"

    onesignal "github.com/OneSignal/onesignal-go-api/v5"
)

restAuth := context.WithValue(
    context.Background(),
    onesignal.RestApiKey,
    os.Getenv("ONESIGNAL_REST_API_KEY"),
)

orgAuth := context.WithValue(
    restAuth,
    onesignal.OrganizationApiKey,
    os.Getenv("ONESIGNAL_ORGANIZATION_API_KEY"),
)

apiClient := onesignal.NewAPIClient(onesignal.NewConfiguration())
```

```php
use onesignal\client\api\DefaultApi;
use onesignal\client\Configuration;
use GuzzleHttp;

$config = Configuration::getDefaultConfiguration()
    ->setRestApiKeyToken(getenv('ONESIGNAL_REST_API_KEY'))
    ->setOrganizationApiKeyToken(getenv('ONESIGNAL_ORGANIZATION_API_KEY'));

$client = new DefaultApi(
    new GuzzleHttp\Client(),
    $config
);
```

```ruby
require 'onesignal'

OneSignal.configure do |config|
  config.rest_api_key = ENV['ONESIGNAL_REST_API_KEY']
  config.organization_api_key = ENV['ONESIGNAL_ORGANIZATION_API_KEY']
end

client = OneSignal::DefaultApi.new
```

```csharp
using OneSignalApi.Api;
using OneSignalApi.Client;

var config = new Configuration();
config.BasePath = "https://api.onesignal.com";
config.AccessToken = Environment.GetEnvironmentVariable("ONESIGNAL_REST_API_KEY");

var client = new DefaultApi(config);
```

```rust
use onesignal_rust_api::apis::configuration::Configuration;
use std::env;

fn create_configuration() -> Configuration {
    let mut config = Configuration::new();
    config.rest_api_key_token = env::var("ONESIGNAL_REST_API_KEY").ok();
    config.organization_api_key_token = env::var("ONESIGNAL_ORGANIZATION_API_KEY").ok();
    config
}
```

--------------------------------

### Example of a URL with UTM parameters

Source: https://documentation.onesignal.com/docs/en/links

A sample URL structure demonstrating the inclusion of utm_source, utm_medium, and utm_campaign parameters.

```text
https://test.com?utm_source=onesignal&utm_medium=push&utm_campaign=2020-06-03-sale-today
```

--------------------------------

### OneSignal.LiveActivities.setupDefault()

Source: https://documentation.onesignal.com/docs/en/mobile-sdk-reference

Allows cross-platform SDKs to manage the lifecycle of a LiveActivity by eliminating the need for a customer app to define and manage their own ActivityAttributes.

```APIDOC
## OneSignal.LiveActivities.setupDefault()

### Description
Allows cross-platform SDKs to manage the lifecycle of a LiveActivity by eliminating the need for a customer app to define and manage their own ActivityAttributes.
```

--------------------------------

### Install OneSignal Expo Plugin

Source: https://documentation.onesignal.com/docs/en/react-native-expo-sdk-setup

Use the Expo CLI to install the required plugin for OneSignal integration.

```shell
npx expo install onesignal-expo-plugin
```

--------------------------------

### Install OneSignal Vue Plugins

Source: https://documentation.onesignal.com/docs/en/vue-js-setup

Use these commands to install the appropriate OneSignal plugin for your Vue project via package managers.

```bash
yarn add onesignal-vue
# or yarn add @onesignal/onesignal-vue3
```

```bash
npm install --save onesignal-vue
# or npm install --save @onesignal/onesignal-vue3
```

--------------------------------

### init()

Source: https://documentation.onesignal.com/docs/en/web-sdk-reference

Initializes the OneSignal SDK. This should be called in the <head> tag once on each page of your site.

```APIDOC
## init()

### Description
Initializes the OneSignal SDK. This should be called in the <head> tag once on each page of your site.

### Parameters
#### Request Body
- **appId** (String) - Required - Your OneSignal App ID.
- **requiresUserPrivacyConsent** (Boolean) - Optional - Delays SDK initialization until the user provides privacy consent.
- **safari_web_id** (String) - Optional - The Safari Web ID for your uploaded Safari .p12 certificate.
- **promptOptions** (Object) - Optional - Customize the permission prompts.
- **notifyButton** (Object) - Optional - Enable and configure the Subscription Bell.
- **welcomeNotification** (Object) - Optional - Customize or disable the welcome notification.
- **persistNotification** (Boolean) - Optional - Chrome (desktop only) - true: notification persists until clicked, false: disappears after a short time.
- **webhooks** (Object) - Optional - Configure event callbacks.
- **autoResubscribe** (Boolean) - Optional - Auto-resubscribes users who clear browser cache or migrate to OneSignal.
- **notificationClickHandlerMatch** (String) - Optional - "exact" (default) or "origin".
- **notificationClickHandlerAction** (String) - Optional - "navigate" (default) or "focus".
- **serviceWorkerParam** (Object) - Optional - Set the scope of the service worker.
- **serviceWorkerPath** (String) - Optional - Set the location of the OneSignal service worker file.

### Request Example
```javascript
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "ONESIGNAL_APP_ID",
  });
});
```
```

--------------------------------

### Webhook Implementation Example (Node.js/Express)

Source: https://documentation.onesignal.com/docs/en/webhooks

A basic example of a Node.js/Express webhook endpoint demonstrating how to receive and process OneSignal webhook data.

```APIDOC
## Webhook Endpoint Example (Node.js/Express)

### Description
This example demonstrates a basic Node.js/Express endpoint for handling OneSignal webhook requests. It includes validation for required fields and a standard success response.

### Code Example
```javascript
// Example webhook endpoint (Node.js/Express)
app.post('/webhook/notification', (req, res) => {
  try {
    const { event, notificationId, additionalData } = req.body;

    // Validate required fields
    if (!event || !notificationId) {
      return res.status(400).json({ error: 'Missing required fields' });
    }

    // Process the webhook data (replace with your actual logic)
    console.log('Received webhook:', req.body);
    // processNotificationEvent(req.body);

    // Always respond with 200 OK for successful processing
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Webhook processing error:', error);
    // Respond with 500 for internal server errors
    res.status(500).json({ error: 'Internal server error' });
  }
});
```
```

--------------------------------

### Initialize OneSignal SDK (Player Model)

Source: https://documentation.onesignal.com/docs/en/device-user-model-web-sdk-mapping

Initialize the OneSignal SDK using the Player Model. Ensure the app ID is correctly set.

```html
<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async></script>
<script>
window.OneSignal = window.OneSignal || [];
OneSignal.push(function() {
  OneSignal.init({
    appId: "YOUR_APP_ID"
  });
});
</script>
```

--------------------------------

### APNs Root Payload Example

Source: https://documentation.onesignal.com/docs/en/osnotification-payload

Example of a push payload where custom data fields are placed in the root alongside the aps dictionary.

```json
{
  "aps": {
    "alert": { "title": "Sale", "body": "20% off all items!" }
  },
  "promo_code": "SPRING20"
}
```

--------------------------------

### Setup Live Activities in Swift

Source: https://documentation.onesignal.com/docs/en/mobile-sdk-reference

Initializes OneSignal to manage the Live Activity lifecycle, including token updates.

```swift
//... your app's code
OneSignal.LiveActivities.setup(MyWidgetAttributes.self);
```

--------------------------------

### Start Live Activity via Push-to-start API

Source: https://documentation.onesignal.com/docs/en/live-activities-developer-setup

Use this cURL request to initiate a Live Activity remotely. Ensure all parameters, including the Widget Attributes struct name, match your configuration exactly.

```bash
curl --location 'https://api.onesignal.com/apps/YOUR_APP_ID/activities/activity/OneSignalWidgetAttributes' \
--header 'Authorization: key YOUR_APP_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "event": "start",
    "activity_id": "push-to-start",
    "included_segments": [
        "Subscribed Users"
    ],
    "event_attributes": {
        "name": "World"
    },
    "event_updates": {
        "emoji":"🤩"
    },
    "name": "Live Activities Test",
    "contents": {
        "en": "A push started this Live Activity"
    },
    "headings": {
      "en": "Live Activity Started"
    }
  }'
```

--------------------------------

### Get Push Token: Player Model vs. User Model

Source: https://documentation.onesignal.com/docs/en/device-user-model-mobile-sdk-mapping

Illustrates how to get the push notification token. The User Model accesses it via `User.pushSubscription.token`.

```swift
OneSignal.getDeviceState().pushToken
```

```swift
OneSignal.User.pushSubscription.token
```

--------------------------------

### Get Notification Permission Status: Player Model vs. User Model

Source: https://documentation.onesignal.com/docs/en/device-user-model-mobile-sdk-mapping

Compares how to get the notification permission status. The User Model uses `Notifications.permissionNative`.

```swift
OneSignal.getDeviceState().notificationPermissionStatus
```

```swift
OneSignal.Notifications.permissionNative
```

--------------------------------

### AI-Driven Installation Prompt

Source: https://documentation.onesignal.com/docs/en/react-native-expo-sdk-setup

A prompt template for AI coding assistants to automate the OneSignal Expo SDK integration.

```text
Integrate the OneSignal Expo SDK into this codebase.

Follow the instructions at:
https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/react-native-expo/ai-prompt.md
```

--------------------------------

### Rendered push click event example

Source: https://documentation.onesignal.com/docs/en/event-streams-data

An example of how a push click event appears after Liquid rendering. Channel-specific fields may be empty depending on the event kind.

```json
{
  "event.kind": "message.push.clicked",
  "event.id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event.timestamp": 1708559115,
  "event.datetime": "2024-02-21T23:45:15.228Z",
  "event.app_id": "your-onesignal-app-id",
  "event.subscription_device_type": "iOS",
  "event.subscription_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "event.onesignal_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "event.external_id": "user_12345",
  "event.data.page_name": "",
  "event.data.page_id": "",
  "event.data.target_name": "",
  "event.data.target_id": "",
  "event.data.failure_reason": ""
}
```

--------------------------------

### Initialize Promo Wheel Interaction

Source: https://documentation.onesignal.com/docs/en/in-app-html-templates

Sets up event listeners for the close button, shop now button, and form submission to trigger the wheel animation and promo logic.

```javascript
window.deal = "";
window.promoCode = "";
window.addEventListener("load", (event) => {
  document
    .querySelector(".close-button")
    .addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });

  document
    .querySelector(".shop-now-button")
    .addEventListener("click", function (e) {
      // Redirect to shopping page
      OneSignalIamApi.close(e);
    });

  document.querySelector("form").addEventListener("submit", function (e) {
    e.preventDefault();
    e.stopPropagation();
    var emailAddress = e.target["email-address"].value;
    var wheel = document.querySelector(".wheel");
    var number = Math.ceil(Math.random() * 10000);
    var edges = [30, 90, 150, 210, 270, 330];
    if (edges.includes(number)) {
      // Add one so that the wheel never lands on an edge 🤫
      number += 1;
    }
    wheel.style.transform = "rotate(" + number + "deg)";
    var results = handlePromoReceived(number);
    var isPromoReceived = results.isPromoReceived;
    var shouldTryAgain = results.shouldTryAgain;

    var resultTimeout = 5000;

    if (isPromoReceived) {
      setTimeout(function () {
        document.querySelector(".shop-now-button").style["display"] =
          "block";
        document.querySelector(
          ".promo-code-code-message"
        ).style["display"] = "flex";
        document.querySelector(
          ".deal"
        ).innerText = window.deal;
        document.querySelector(
          ".promo-code"
        ).innerText = window.promoCode;
        document.querySelector(".wheel-container .stopper").style[
          "display"
        ] = "none";
        document.querySelector("form").style["display"] = "none";
```

--------------------------------

### WP Engine HTML Post-Processing Example

Source: https://documentation.onesignal.com/docs/en/troubleshooting-wordpress-web-push

This is an example of HTML Post-Processing rules for WP Engine to correctly serve OneSignal SDK files. Consult WP Engine support for your specific configuration.

```nginx
#https?://(www\.)?(YOURSITEHERE\.com|mywpenginehandleHere.wpengine.com|wpengineCDNpathHere.wpengine.netdna-(ssl|cdn).com)/wp-(content|includes)#
=> https://wpengineCDNpathHere-wpengine.netdna-ssl.com/wp-$4
#https://wpengineCDNpathHere-wpengine.netdna-ssl.com/plugins/onesignal-free-web-push-notifications/#
=> https://mywebsiteHere.com/wp-content/plugins/onesignal-free-web-push-notifications/
#https://wpengineCDNpathHere-wpengine.netdna-ssl.com/wp-content/plugins/onesignal-free-web-push-notifications/#
=> https://mywebsiteHere.com/wp-content/plugins/onesignal-free-web-push-notifications/
```

--------------------------------

### Language Settings

Source: https://documentation.onesignal.com/docs/en/web-sdk-reference

Get or set the language of the current user.

```APIDOC
## GET/POST Language Settings

### Description
Get or override the auto-detected language of the user.

### Methods
- getLanguage()
- setLanguage(languageCode)

### Parameters
#### Request Body
- **languageCode** (string) - The language code (e.g., 'en').
```

--------------------------------

### Initialize OneSignal SDK (User Model)

Source: https://documentation.onesignal.com/docs/en/device-user-model-web-sdk-mapping

Initialize the OneSignal SDK using the User Model. This version uses a deferred loading script and requires an await for initialization.

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