Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/onesignal/onesignal-vue

Vue OneSignal Plugin: Make it easy to integrate OneSignal with your Vue App!
https://github.com/onesignal/onesignal-vue

email in-app-messaging notifications onesignal push push-notifications sms vue vuejs web

Last synced: 7 days ago
JSON representation

Vue OneSignal Plugin: Make it easy to integrate OneSignal with your Vue App!

Host: GitHub
URL: https://github.com/onesignal/onesignal-vue
Owner: OneSignal
License: other
Created: 2021-07-23T22:36:54.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2023-08-31T22:26:34.000Z (about 1 year ago)
Last Synced: 2024-11-09T08:48:55.027Z (7 days ago)
Topics: email, in-app-messaging, notifications, onesignal, push, push-notifications, sms, vue, vuejs, web
Language: TypeScript
Homepage:
Size: 93.8 KB
Stars: 13
Watchers: 34
Forks: 3
Open Issues: 5
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        
welcome to onesignal-vue 👋




  

    

  

  

    

  

  

    

  

  

    

  



> This is a JavaScript module that can be used to easily include [OneSignal](https://onesignal.com/) code in a website or app that uses Vue for its front-end codebase.

* 🏠 [Homepage](https://onesignal.com)

* 🖤 [npm](https://www.npmjs.com/package/onesignal-vue)

OneSignal is the world's leader for Mobile Push Notifications, Web Push, and In-App Messaging. It is trusted by 800k businesses to send 5 billion Push Notifications per day.

You can find more information on OneSignal [here](https://onesignal.com/).

> Upgrading from Version 1?

See our [migration guide](./MigrationGuide.md) if coming from v1.

## Contents

- [Install](#install)

- [Usage](#usage)

- [API](#onesignal-api)

- [Advanced Usage](#advanced-usage)

---

## Vue Compatibility

Make sure you install a plugin version compatible with your Vue environment.

| Vue | OneSignal Plugin |

|-----|------------------|

| 2   | onesignal-vue              |

| 3   | [onesignal-vue3](https://github.com/OneSignal/onesignal-vue3)               |

---

## Install

You can use `yarn` or `npm`.

### Yarn

```bash

yarn add onesignal-vue

```

### npm

```bash

npm install --save onesignal-vue

```

---

## Usage

## Plugin setup

```js

import Vue from 'vue'

import OneSignalVue from 'onesignal-vue'

Vue.use(OneSignalVue);

```

Initialize OneSignal with your `appId` via the `options` parameter:

```js

new Vue({

  render: h => h(App),

  beforeMount() {

    this.$OneSignal.init({ appId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' });

  }

}).$mount('#app')

```

The `init` function returns a promise that resolves when OneSignal is loaded.

**Examples**

```js

await this.$OneSignal.init({ appId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' });

// do other stuff

```

```js

this.$OneSignal.init({ appId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' }).then(() => {

  // do other stuff

});

```

### Code completion

For code completion to work correctly, make sure you import the plugin (e.g: in child components).

```vue

import OneSignalVue from 'onesignal-vue';

export default {

  name: 'HelloWorld',

  props: {

    msg: String

  },

  beforeCreate() {

    // Example prompting for notification permission

    this.$OneSignal.User.PushSubscription.optIn();

  }

}

```

### Init Options

You can pass other [options](https://documentation.onesignal.com/v11.0/docs/web-sdk#initializing-the-sdk) to the `init` function. Use these options to configure personalized prompt options, auto-resubscribe, and more.

  Expand to see more options

  | Property Name               | Type                  | Description                                        |

| ---------------------------| --------------------- | -------------------------------------------------- |

| `appId`                     | `string`              | The ID of your OneSignal app.                      |

| `autoRegister`              | `boolean` (optional)  | Whether or not to automatically register the user. |

| `autoResubscribe`           | `boolean` (optional)  | Whether or not to automatically resubscribe the user. |

| `path`                      | `string` (optional)   | The path to the OneSignal service worker file.     |

| `serviceWorkerPath`         | `string` (optional)   | The path to the OneSignal service worker script.   |

| `serviceWorkerUpdaterPath`  | `string` (optional)   | The path to the OneSignal service worker updater script. |

| `subdomainName`             | `string` (optional)   | The subdomain of your OneSignal app.               |

| `allowLocalhostAsSecureOrigin` | `boolean` (optional) | Whether or not to allow localhost as a secure origin. |

| `requiresUserPrivacyConsent`| `boolean` (optional)  | Whether or not the user's consent is required.     |

| `persistNotification`       | `boolean` (optional)  | Whether or not notifications should persist.       |

| `notificationClickHandlerMatch`| `string` (optional) | The URL match pattern for notification clicks.     |

| `notificationClickHandlerAction`| `string` (optional)| The action to perform when a notification is clicked. |

| `welcomeNotification`       | `object` (optional)   | The welcome notification configuration.            |

| `notifyButton`              | `object` (optional)   | The notify button configuration.                   |

| `promptOptions`             | `object` (optional)   | Additional options for the subscription prompt.    |

| `webhooks`                  | `object` (optional)   | The webhook configuration.                         |

| `[key: string]`             | `any`                 | Additional properties can be added as needed.      |

**Service Worker Params**

You can customize the location and filenames of service worker assets. You are also able to specify the specific scope that your service worker should control. You can read more [here](https://documentation.onesignal.com/docs/onesignal-service-worker-faq#sdk-parameter-reference-for-service-workers).

In this distribution, you can specify the parameters via the following:

| Field                      | Details                                                                                                                |

|----------------------------|------------------------------------------------------------------------------------------------------------------------|

| `serviceWorkerParam`       | Use to specify the scope, or the path the service worker has control of.  Example:  `{ scope: "/js/push/onesignal/" }` |

| `serviceWorkerPath`        | The path to the service worker file.                                                                                   |

---

### Service Worker File

If you haven't done so already, you will need to add the [OneSignal Service Worker file](https://github.com/OneSignal/OneSignal-Website-SDK/files/7585231/OneSignal-Web-SDK-HTTPS-Integration-Files.zip) to your site ([learn more](https://documentation.onesignal.com/docs/web-push-quickstart#step-6-upload-files)).

The OneSignal SDK file must be publicly accessible. You can put them in your top-level root or a subdirectory. However, if you are placing the file not on top-level root make sure to specify the path via the service worker params in the init options (see section above).

**Tip:**

Visit `https://yoursite.com/OneSignalSDKWorker.js` in the address bar to make sure the files are being served successfully.

---

### Typescript

This package includes Typescript support.

```ts

interface IOneSignalOneSignal {

	Slidedown: IOneSignalSlidedown;

	Notifications: IOneSignalNotifications;

	Session: IOneSignalSession;

	User: IOneSignalUser;

	Debug: IOneSignalDebug;

	login(externalId: string, jwtToken?: string): Promise;

	logout(): Promise;

	init(options: IInitObject): Promise;

	setConsentGiven(consent: boolean): Promise;

	setConsentRequired(requiresConsent: boolean): Promise;

}

```

### OneSignal API

See the official [OneSignal WebSDK reference](https://documentation.onesignal.com/v11.0/docs/web-sdk#initializing-the-sdk) for information on all available SDK functions.

---

## Advanced Usage

### Events and Event Listeners

Use listeners to react to OneSignal-related events:

### Notifications Namespace

| Event Name | Callback Argument Type |

|-|-|

|'click'      | NotificationClickEvent|

|'foregroundWillDisplay'| NotificationForegroundWillDisplayEvent

| 'dismiss'| NotificationDismissEvent|

|'permissionChange'| boolean|

|'permissionPromptDisplay'| void|

### Slidedown Namespace

| Event Name | Callback Argument Type |

|-|-|

|'slidedownShown'      | boolean |

### Push Subscription Namespace

| Event Name | Callback Argument Type |

|-|-|

|'change'      | boolean |

**Example**

```js

OneSignal.Notifications.addEventListener('click', (event) => {

  console.log("The notification was clicked!", event);

});

```

See the [OneSignal WebSDK Reference](https://documentation.onesignal.com/v11.0/docs/web-sdk#initializing-the-sdk) for all available event listeners.

---

## 🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check [issues page](https://github.com/OneSignal/onesignal-vue/issues).

## Show your support

Give a ⭐️ if this project helped you!

## OneSignal

* [Website](https://onesignal.com)

* Twitter: [@onesignal](https://twitter.com/onesignal)

* Github: [@OneSignal](https://github.com/OneSignal)

* LinkedIn: [@onesignal](https://linkedin.com/company/onesignal)

## Discord

Reach out to us via our [Discord server](https://discord.com/invite/EP7gf6Uz7G)!

## 📝 License

Copyright © 2022 [OneSignal](https://github.com/OneSignal).


This project is [Modified MIT](https://github.com/OneSignal/onesignal-vue/blob/main/LICENSE) licensed.

Enjoy!