npm package: @fidaktk/onesignal-capacitor
Description: Capacitor plugin for OneSignal push notifications SDK v5 — native Android & iOS integration with full event support
Author: Fida ur Rehman
Latest version: 1.0.1

# @fidaktk/onesignal-capacitor

[![npm version](https://img.shields.io/npm/v/@fidaktk/onesignal-capacitor.svg)](https://www.npmjs.com/package/@fidaktk/onesignal-capacitor)
[![license](https://img.shields.io/npm/l/@fidaktk/onesignal-capacitor.svg)](https://github.com/fidaktk/onesignal-capacitor/blob/main/LICENSE)

Capacitor 8 plugin for [OneSignal](https://onesignal.com) push notifications (SDK v5). Native Android & iOS -- no Cordova dependency.

## Requirements

| Dependency         | Version        |
|--------------------|----------------|
| Capacitor          | >= 8.0.0       |
| Android minSdk     | 24 (Android 7) |
| iOS deployment     | 15.0+          |
| OneSignal SDK      | 5.x            |

**Before you start:** Create a [OneSignal account](https://onesignal.com), set up an app in the dashboard, and grab your **App ID**. You'll also need platform credentials configured in OneSignal:
- **Android:** Firebase Cloud Messaging (FCM) server key -- requires a [Firebase project](https://console.firebase.google.com)
- **iOS:** APNs authentication key (p8) or certificate (p12) -- from [Apple Developer](https://developer.apple.com/account)

## Install

```bash
npm install @fidaktk/onesignal-capacitor
npx cap sync
```

No manual plugin registration is needed -- Capacitor auto-discovers the plugin.

## Android Setup

1. Download `google-services.json` from your Firebase project and place it in `android/app/`.

2. In your **project-level** `android/build.gradle`, add:

    ```groovy
    buildscript {
        dependencies {
            classpath 'com.google.gms:google-services:4.4.0'
        }
    }
    ```

3. In your **app-level** `android/app/build.gradle`, add at the top:

    ```groovy
    apply plugin: 'com.google.gms.google-services'
    ```

That's it. The OneSignal SDK auto-registers its permissions and receivers.

## iOS Setup

1. In Xcode, select your app target > **Signing & Capabilities**, then add:
   - **Push Notifications**
   - **Background Modes** > check **Remote notifications**

2. **(Recommended)** Add a **Notification Service Extension** for rich push (images, action buttons, badge counts):

   a. **File > New > Target > Notification Service Extension**. Name it `OneSignalNotificationServiceExtension`.

   b. Set its deployment target to **iOS 15.0**.

   c. Add the extension target to your `ios/App/Podfile`:

   ```ruby
   target 'OneSignalNotificationServiceExtension' do
     use_frameworks!
     pod 'OneSignalXCFramework', '~> 5.2'
   end
   ```

   d. Replace `NotificationService.swift` with:

   ```swift
   import UserNotifications
   import OneSignalExtension

   class NotificationService: UNNotificationServiceExtension {
       var contentHandler: ((UNNotificationContent) -> Void)?
       var receivedRequest: UNNotificationRequest!
       var bestAttemptContent: UNMutableNotificationContent?

       override func didReceive(
           _ request: UNNotificationRequest,
           withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
       ) {
           self.receivedRequest = request
           self.contentHandler = contentHandler
           self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

           if let bestAttemptContent = bestAttemptContent {
               OneSignalExtension.didReceiveNotificationExtensionRequest(
                   self.receivedRequest,
                   with: bestAttemptContent,
                   withContentHandler: self.contentHandler
               )
           }
       }

       override func serviceExtensionTimeWillExpire() {
           if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
               OneSignalExtension.serviceExtensionTimeWillExpireRequest(
                   self.receivedRequest, with: bestAttemptContent
               )
               contentHandler(bestAttemptContent)
           }
       }
   }
   ```

   e. Run `cd ios/App && pod install`.

## Quick Start

```typescript
import { OneSignalPlugin } from '@fidaktk/onesignal-capacitor';
import type {
  OneSignalNotification,
  PushSubscriptionChangedState,
} from '@fidaktk/onesignal-capacitor';

// Call once at app startup (e.g. app.component.ts, main.ts, App.tsx)
async function initOneSignal() {
  // Initialize with your OneSignal App ID
  await OneSignalPlugin.initialize({ appId: 'YOUR_ONESIGNAL_APP_ID' });

  // Request push permission
  const { permission } = await OneSignalPlugin.requestNotificationPermission({
    fallbackToSettings: true,
  });
  console.log('Permission:', permission);

  // Handle notification taps (including cold-start launches)
  OneSignalPlugin.addListener(
    'notificationClicked',
    (event: OneSignalNotification) => {
      console.log('Clicked:', event.notificationId, event.additionalData);
    },
  );

  // Handle foreground notifications
  OneSignalPlugin.addListener(
    'notificationWillDisplay',
    (event: OneSignalNotification) => {
      // Show it (or omit this call to suppress)
      OneSignalPlugin.displayNotification({
        notificationId: event.notificationId,
      });
    },
  );

  // Track push token changes
  OneSignalPlugin.addListener(
    'pushSubscriptionChange',
    (state: PushSubscriptionChangedState) => {
      console.log('Token:', state.current.token);
    },
  );
}
```

## Usage

### User Identity

```typescript
// After authentication
await OneSignalPlugin.login({ externalId: 'user-123' });

// On logout
await OneSignalPlugin.logout();
```

### Tags

```typescript
await OneSignalPlugin.addTag({ key: 'plan', value: 'premium' });
await OneSignalPlugin.addTags({ tags: { plan: 'premium', role: 'admin' } });

const { tags } = await OneSignalPlugin.getTags();

await OneSignalPlugin.removeTag({ key: 'plan' });
await OneSignalPlugin.removeTags({ keys: ['plan', 'role'] });
```

### Push Subscription

```typescript
const state = await OneSignalPlugin.getPushSubscriptionState();
console.log(state.token, state.optedIn);

await OneSignalPlugin.optInPushSubscription();
await OneSignalPlugin.optOutPushSubscription();
```

### Email & SMS

```typescript
await OneSignalPlugin.addEmail({ email: 'user@example.com' });
await OneSignalPlugin.addSms({ smsNumber: '+15551234567' });
```

### In-App Messages

```typescript
await OneSignalPlugin.addInAppMessageTrigger({ key: 'screen', value: 'home' });
await OneSignalPlugin.setInAppMessagesPaused({ paused: true });

OneSignalPlugin.addListener('inAppMessageClicked', (action) => {
  console.log(action.clickName, action.clickUrl);
});
```

### Outcomes

```typescript
await OneSignalPlugin.addOutcome({ name: 'purchase' });
await OneSignalPlugin.addUniqueOutcome({ name: 'app_open' });
await OneSignalPlugin.addOutcomeWithValue({ name: 'revenue', value: 9.99 });
```

### GDPR Consent

```typescript
// Call BEFORE initialize()
await OneSignalPlugin.setConsentRequired({ required: true });

// After user consents
await OneSignalPlugin.setConsentGiven({ given: true });

// Then initialize
await OneSignalPlugin.initialize({ appId: 'YOUR_APP_ID' });
```

### Debug Logging

```typescript
import { LogLevel } from '@fidaktk/onesignal-capacitor';

// Set before initialize() to capture init logs
await OneSignalPlugin.setLogLevel({ level: LogLevel.Verbose });
await OneSignalPlugin.initialize({ appId: 'YOUR_APP_ID' });
```

## Foreground Notifications

When a notification arrives while the app is in the foreground, the `notificationWillDisplay` event fires. The notification is **not** shown automatically -- you decide:

```typescript
OneSignalPlugin.addListener('notificationWillDisplay', (event) => {
  // Option A: Show it
  OneSignalPlugin.displayNotification({ notificationId: event.notificationId });

  // Option B: Do nothing (suppressed)
});
```

If you don't call `displayNotification` within 25 seconds, it auto-displays as a safety fallback.

## API

<docgen-index>

* [`initialize(...)`](#initialize)
* [`login(...)`](#login)
* [`logout()`](#logout)
* [`setConsentRequired(...)`](#setconsentrequired)
* [`setConsentGiven(...)`](#setconsentgiven)
* [`addTag(...)`](#addtag)
* [`addTags(...)`](#addtags)
* [`getTags()`](#gettags)
* [`removeTag(...)`](#removetag)
* [`removeTags(...)`](#removetags)
* [`addAlias(...)`](#addalias)
* [`addAliases(...)`](#addaliases)
* [`removeAlias(...)`](#removealias)
* [`removeAliases(...)`](#removealiases)
* [`addEmail(...)`](#addemail)
* [`removeEmail(...)`](#removeemail)
* [`addSms(...)`](#addsms)
* [`removeSms(...)`](#removesms)
* [`setLanguage(...)`](#setlanguage)
* [`getPushSubscriptionState()`](#getpushsubscriptionstate)
* [`optInPushSubscription()`](#optinpushsubscription)
* [`optOutPushSubscription()`](#optoutpushsubscription)
* [`requestNotificationPermission(...)`](#requestnotificationpermission)
* [`getNotificationPermission()`](#getnotificationpermission)
* [`canRequestNotificationPermission()`](#canrequestnotificationpermission)
* [`displayNotification(...)`](#displaynotification)
* [`addInAppMessageTrigger(...)`](#addinappmessagetrigger)
* [`addInAppMessageTriggers(...)`](#addinappmessagetriggers)
* [`removeInAppMessageTrigger(...)`](#removeinappmessagetrigger)
* [`removeInAppMessageTriggers(...)`](#removeinappmessagetriggers)
* [`clearInAppMessageTriggers()`](#clearinappmessagetriggers)
* [`setInAppMessagesPaused(...)`](#setinappmessagespaused)
* [`getInAppMessagesPaused()`](#getinappmessagespaused)
* [`addOutcome(...)`](#addoutcome)
* [`addUniqueOutcome(...)`](#adduniqueoutcome)
* [`addOutcomeWithValue(...)`](#addoutcomewithvalue)
* [`setLocationShared(...)`](#setlocationshared)
* [`requestLocationPermission()`](#requestlocationpermission)
* [`setLogLevel(...)`](#setloglevel)
* [`setAlertLevel(...)`](#setalertlevel)
* [`addListener('notificationClicked', ...)`](#addlistenernotificationclicked-)
* [`addListener('notificationWillDisplay', ...)`](#addlistenernotificationwilldisplay-)
* [`addListener('pushSubscriptionChange', ...)`](#addlistenerpushsubscriptionchange-)
* [`addListener('permissionChange', ...)`](#addlistenerpermissionchange-)
* [`addListener('inAppMessageClicked', ...)`](#addlistenerinappmessageclicked-)
* [`addListener('inAppMessageLifecycle', ...)`](#addlistenerinappmessagelifecycle-)
* [`removeAllListeners()`](#removealllisteners)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)

</docgen-index>

<docgen-api>
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->

### initialize(...)

```typescript
initialize(options: { appId: string; }) => Promise<void>
```

Initialize the OneSignal SDK. Must be called before any other method.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | <code>{ appId: string; }</code> |

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


### login(...)

```typescript
login(options: { externalId: string; }) => Promise<void>
```

Identify the current user by an external ID. Call on every app launch
when you know the user's identity. Creates or retrieves the OneSignal
user associated with this external ID.

| Param         | Type                                 |
| ------------- | ------------------------------------ |
| **`options`** | <code>{ externalId: string; }</code> |

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


### logout()

```typescript
logout() => Promise<void>
```

Log the user out. Reverts to an anonymous device-scoped user.

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


### setConsentRequired(...)

```typescript
setConsentRequired(options: { required: boolean; }) => Promise<void>
```

Require user consent before the SDK collects any data.
Must be called **before** {@link initialize}.

| Param         | Type                                |
| ------------- | ----------------------------------- |
| **`options`** | <code>{ required: boolean; }</code> |

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


### setConsentGiven(...)

```typescript
setConsentGiven(options: { given: boolean; }) => Promise<void>
```

Indicate that the user has given (or revoked) data collection consent.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | <code>{ given: boolean; }</code> |

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


### addTag(...)

```typescript
addTag(options: { key: string; value: string; }) => Promise<void>
```

Set a single tag on the current user.

| Param         | Type                                         |
| ------------- | -------------------------------------------- |
| **`options`** | <code>{ key: string; value: string; }</code> |

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


### addTags(...)

```typescript
addTags(options: { tags: Record<string, string>; }) => Promise<void>
```

Set multiple tags on the current user at once.

| Param         | Type                                                                       |
| ------------- | -------------------------------------------------------------------------- |
| **`options`** | <code>{ tags: <a href="#record">Record</a>&lt;string, string&gt;; }</code> |

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


### getTags()

```typescript
getTags() => Promise<{ tags: Record<string, string>; }>
```

Get all tags currently set on the user (local cache).

**Returns:** <code>Promise&lt;{ tags: <a href="#record">Record</a>&lt;string, string&gt;; }&gt;</code>

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


### removeTag(...)

```typescript
removeTag(options: { key: string; }) => Promise<void>
```

Remove a single tag from the current user.

| Param         | Type                          |
| ------------- | ----------------------------- |
| **`options`** | <code>{ key: string; }</code> |

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


### removeTags(...)

```typescript
removeTags(options: { keys: string[]; }) => Promise<void>
```

Remove multiple tags from the current user at once.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | <code>{ keys: string[]; }</code> |

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


### addAlias(...)

```typescript
addAlias(options: { label: string; id: string; }) => Promise<void>
```

Add an alias for the current user.

| Param         | Type                                        |
| ------------- | ------------------------------------------- |
| **`options`** | <code>{ label: string; id: string; }</code> |

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


### addAliases(...)

```typescript
addAliases(options: { aliases: Record<string, string>; }) => Promise<void>
```

Add multiple aliases for the current user at once.

| Param         | Type                                                                          |
| ------------- | ----------------------------------------------------------------------------- |
| **`options`** | <code>{ aliases: <a href="#record">Record</a>&lt;string, string&gt;; }</code> |

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


### removeAlias(...)

```typescript
removeAlias(options: { label: string; }) => Promise<void>
```

Remove an alias from the current user.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | <code>{ label: string; }</code> |

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


### removeAliases(...)

```typescript
removeAliases(options: { labels: string[]; }) => Promise<void>
```

Remove multiple aliases from the current user at once.

| Param         | Type                               |
| ------------- | ---------------------------------- |
| **`options`** | <code>{ labels: string[]; }</code> |

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


### addEmail(...)

```typescript
addEmail(options: { email: string; }) => Promise<void>
```

Add an email subscription to the current user.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | <code>{ email: string; }</code> |

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


### removeEmail(...)

```typescript
removeEmail(options: { email: string; }) => Promise<void>
```

Remove an email subscription from the current user.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | <code>{ email: string; }</code> |

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


### addSms(...)

```typescript
addSms(options: { smsNumber: string; }) => Promise<void>
```

Add an SMS subscription to the current user.

| Param         | Type                                |
| ------------- | ----------------------------------- |
| **`options`** | <code>{ smsNumber: string; }</code> |

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


### removeSms(...)

```typescript
removeSms(options: { smsNumber: string; }) => Promise<void>
```

Remove an SMS subscription from the current user.

| Param         | Type                                |
| ------------- | ----------------------------------- |
| **`options`** | <code>{ smsNumber: string; }</code> |

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


### setLanguage(...)

```typescript
setLanguage(options: { language: string; }) => Promise<void>
```

Override the auto-detected device language for the current user.

| Param         | Type                               |
| ------------- | ---------------------------------- |
| **`options`** | <code>{ language: string; }</code> |

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


### getPushSubscriptionState()

```typescript
getPushSubscriptionState() => Promise<PushSubscriptionState>
```

Get the current push subscription state (ID, token, opted-in status).

**Returns:** <code>Promise&lt;<a href="#pushsubscriptionstate">PushSubscriptionState</a>&gt;</code>

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


### optInPushSubscription()

```typescript
optInPushSubscription() => Promise<void>
```

Opt the current device into push notifications.

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


### optOutPushSubscription()

```typescript
optOutPushSubscription() => Promise<void>
```

Opt the current device out of push notifications.

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


### requestNotificationPermission(...)

```typescript
requestNotificationPermission(options?: { fallbackToSettings?: boolean | undefined; } | undefined) => Promise<{ permission: boolean; }>
```

Show the native push notification permission prompt.

| Param         | Type                                           |
| ------------- | ---------------------------------------------- |
| **`options`** | <code>{ fallbackToSettings?: boolean; }</code> |

**Returns:** <code>Promise&lt;{ permission: boolean; }&gt;</code>

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


### getNotificationPermission()

```typescript
getNotificationPermission() => Promise<{ permission: boolean; }>
```

Check the current notification permission status without prompting.

**Returns:** <code>Promise&lt;{ permission: boolean; }&gt;</code>

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


### canRequestNotificationPermission()

```typescript
canRequestNotificationPermission() => Promise<{ canRequest: boolean; }>
```

Check whether the permission prompt can be shown (i.e., user hasn't
permanently denied it).

**Returns:** <code>Promise&lt;{ canRequest: boolean; }&gt;</code>

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


### displayNotification(...)

```typescript
displayNotification(options: { notificationId: string; }) => Promise<void>
```

Display a foreground notification that was intercepted by the
`notificationWillDisplay` listener. If not called within 25 seconds,
the notification displays automatically.

| Param         | Type                                     |
| ------------- | ---------------------------------------- |
| **`options`** | <code>{ notificationId: string; }</code> |

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


### addInAppMessageTrigger(...)

```typescript
addInAppMessageTrigger(options: { key: string; value: string; }) => Promise<void>
```

Add a trigger that controls when in-app messages are displayed.

| Param         | Type                                         |
| ------------- | -------------------------------------------- |
| **`options`** | <code>{ key: string; value: string; }</code> |

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


### addInAppMessageTriggers(...)

```typescript
addInAppMessageTriggers(options: { triggers: Record<string, string>; }) => Promise<void>
```

Add multiple in-app message triggers at once.

| Param         | Type                                                                           |
| ------------- | ------------------------------------------------------------------------------ |
| **`options`** | <code>{ triggers: <a href="#record">Record</a>&lt;string, string&gt;; }</code> |

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


### removeInAppMessageTrigger(...)

```typescript
removeInAppMessageTrigger(options: { key: string; }) => Promise<void>
```

Remove an in-app message trigger.

| Param         | Type                          |
| ------------- | ----------------------------- |
| **`options`** | <code>{ key: string; }</code> |

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


### removeInAppMessageTriggers(...)

```typescript
removeInAppMessageTriggers(options: { keys: string[]; }) => Promise<void>
```

Remove multiple in-app message triggers at once.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | <code>{ keys: string[]; }</code> |

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


### clearInAppMessageTriggers()

```typescript
clearInAppMessageTriggers() => Promise<void>
```

Remove all in-app message triggers.

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


### setInAppMessagesPaused(...)

```typescript
setInAppMessagesPaused(options: { paused: boolean; }) => Promise<void>
```

Pause or resume in-app message display.

| Param         | Type                              |
| ------------- | --------------------------------- |
| **`options`** | <code>{ paused: boolean; }</code> |

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


### getInAppMessagesPaused()

```typescript
getInAppMessagesPaused() => Promise<{ paused: boolean; }>
```

Check if in-app messages are currently paused.

**Returns:** <code>Promise&lt;{ paused: boolean; }&gt;</code>

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


### addOutcome(...)

```typescript
addOutcome(options: { name: string; }) => Promise<void>
```

Track a custom outcome event.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | <code>{ name: string; }</code> |

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


### addUniqueOutcome(...)

```typescript
addUniqueOutcome(options: { name: string; }) => Promise<void>
```

Track a unique outcome (counted only once per session).

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | <code>{ name: string; }</code> |

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


### addOutcomeWithValue(...)

```typescript
addOutcomeWithValue(options: { name: string; value: number; }) => Promise<void>
```

Track an outcome with a numeric value (e.g. revenue).

| Param         | Type                                          |
| ------------- | --------------------------------------------- |
| **`options`** | <code>{ name: string; value: number; }</code> |

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


### setLocationShared(...)

```typescript
setLocationShared(options: { shared: boolean; }) => Promise<void>
```

Enable or disable sharing the user's location with OneSignal.

| Param         | Type                              |
| ------------- | --------------------------------- |
| **`options`** | <code>{ shared: boolean; }</code> |

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


### requestLocationPermission()

```typescript
requestLocationPermission() => Promise<void>
```

Request location permission from the user.

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


### setLogLevel(...)

```typescript
setLogLevel(options: { level: number; }) => Promise<void>
```

Set the SDK log output level.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | <code>{ level: number; }</code> |

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


### setAlertLevel(...)

```typescript
setAlertLevel(options: { level: number; }) => Promise<void>
```

Set the log level for alert dialogs (shown to the user on device).

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | <code>{ level: number; }</code> |

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


### addListener('notificationClicked', ...)

```typescript
addListener(eventName: 'notificationClicked', listenerFunc: (event: OneSignalNotification) => void) => Promise<PluginListenerHandle>
```

Fired when the user taps a notification (including cold-start launches).

| Param              | Type                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------- |
| **`eventName`**    | <code>'notificationClicked'</code>                                                          |
| **`listenerFunc`** | <code>(event: <a href="#onesignalnotification">OneSignalNotification</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

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


### addListener('notificationWillDisplay', ...)

```typescript
addListener(eventName: 'notificationWillDisplay', listenerFunc: (event: OneSignalNotification) => void) => Promise<PluginListenerHandle>
```

Fired when a notification is received while the app is in the foreground.
Call {@link displayNotification} with the `notificationId` to show it,
or do nothing to suppress it.

| Param              | Type                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------- |
| **`eventName`**    | <code>'notificationWillDisplay'</code>                                                      |
| **`listenerFunc`** | <code>(event: <a href="#onesignalnotification">OneSignalNotification</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

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


### addListener('pushSubscriptionChange', ...)

```typescript
addListener(eventName: 'pushSubscriptionChange', listenerFunc: (event: PushSubscriptionChangedState) => void) => Promise<PluginListenerHandle>
```

Fired when the push subscription state changes (token, opt-in status).

| Param              | Type                                                                                                      |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| **`eventName`**    | <code>'pushSubscriptionChange'</code>                                                                     |
| **`listenerFunc`** | <code>(event: <a href="#pushsubscriptionchangedstate">PushSubscriptionChangedState</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

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


### addListener('permissionChange', ...)

```typescript
addListener(eventName: 'permissionChange', listenerFunc: (event: { permission: boolean; }) => void) => Promise<PluginListenerHandle>
```

Fired when notification permission status changes.

| Param              | Type                                                      |
| ------------------ | --------------------------------------------------------- |
| **`eventName`**    | <code>'permissionChange'</code>                           |
| **`listenerFunc`** | <code>(event: { permission: boolean; }) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

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


### addListener('inAppMessageClicked', ...)

```typescript
addListener(eventName: 'inAppMessageClicked', listenerFunc: (event: InAppMessageAction) => void) => Promise<PluginListenerHandle>
```

Fired when the user clicks an element in an in-app message.

| Param              | Type                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------- |
| **`eventName`**    | <code>'inAppMessageClicked'</code>                                                    |
| **`listenerFunc`** | <code>(event: <a href="#inappmessageaction">InAppMessageAction</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

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


### addListener('inAppMessageLifecycle', ...)

```typescript
addListener(eventName: 'inAppMessageLifecycle', listenerFunc: (event: InAppMessageLifecycleEvent) => void) => Promise<PluginListenerHandle>
```

Fired during in-app message lifecycle transitions.

| Param              | Type                                                                                                  |
| ------------------ | ----------------------------------------------------------------------------------------------------- |
| **`eventName`**    | <code>'inAppMessageLifecycle'</code>                                                                  |
| **`listenerFunc`** | <code>(event: <a href="#inappmessagelifecycleevent">InAppMessageLifecycleEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

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


### removeAllListeners()

```typescript
removeAllListeners() => Promise<void>
```

Remove all registered event listeners.

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


### Interfaces


#### PushSubscriptionState

Current state of the device's push subscription.

| Prop          | Type                 | Description                                         |
| ------------- | -------------------- | --------------------------------------------------- |
| **`id`**      | <code>string</code>  | OneSignal subscription ID for this device.          |
| **`token`**   | <code>string</code>  | Push token (FCM on Android, APNs on iOS).           |
| **`optedIn`** | <code>boolean</code> | Whether the user is opted in to push notifications. |


#### PluginListenerHandle

| Prop         | Type                                      |
| ------------ | ----------------------------------------- |
| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |


#### OneSignalNotification

Represents a OneSignal push notification.

| Prop                 | Type                                                             | Description                                                      |
| -------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------- |
| **`notificationId`** | <code>string</code>                                              | Unique notification identifier.                                  |
| **`title`**          | <code>string</code>                                              | Notification title.                                              |
| **`body`**           | <code>string</code>                                              | Notification body text.                                          |
| **`sound`**          | <code>string</code>                                              | Sound file name.                                                 |
| **`badgeCount`**     | <code>number</code>                                              | Badge count (iOS).                                               |
| **`launchUrl`**      | <code>string</code>                                              | URL to open when notification is tapped.                         |
| **`rawPayload`**     | <code>string</code>                                              | Raw notification payload as a JSON string.                       |
| **`additionalData`** | <code><a href="#record">Record</a>&lt;string, unknown&gt;</code> | Custom key-value data attached to the notification.              |
| **`actionId`**       | <code>string</code>                                              | Action button ID that was tapped (only present on click events). |


#### PushSubscriptionChangedState

Emitted when push subscription state changes.

| Prop           | Type                                                                    | Description                  |
| -------------- | ----------------------------------------------------------------------- | ---------------------------- |
| **`previous`** | <code><a href="#pushsubscriptionstate">PushSubscriptionState</a></code> | Previous subscription state. |
| **`current`**  | <code><a href="#pushsubscriptionstate">PushSubscriptionState</a></code> | Current subscription state.  |


#### InAppMessageAction

Data from an in-app message click event.

| Prop                | Type                 | Description                                      |
| ------------------- | -------------------- | ------------------------------------------------ |
| **`clickName`**     | <code>string</code>  | Action element name that was clicked.            |
| **`clickUrl`**      | <code>string</code>  | URL associated with the clicked element.         |
| **`firstClick`**    | <code>boolean</code> | Whether this is the first click on this message. |
| **`closesMessage`** | <code>boolean</code> | Whether this click closes the message.           |


#### InAppMessageLifecycleEvent

In-app message lifecycle event.

| Prop            | Type                                                                        | Description                |
| --------------- | --------------------------------------------------------------------------- | -------------------------- |
| **`type`**      | <code>'willDisplay' \| 'didDisplay' \| 'willDismiss' \| 'didDismiss'</code> | Lifecycle stage.           |
| **`messageId`** | <code>string</code>                                                         | Unique message identifier. |


### Type Aliases


#### Record

Construct a type with a set of properties K of type T

<code>{ [P in K]: T; }</code>

</docgen-api>

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

[MIT](./LICENSE)