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: about 1 month 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 (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2023-08-31T22:26:34.000Z (almost 2 years ago)
- Last Synced: 2024-11-09T08:48:55.027Z (7 months 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
### npm
```bash
npm install --save onesignal-vue
```
### Yarn
```bash
yarn add 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
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/11480764/OneSignalSDK-v16-ServiceWorker.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
this.$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!