onesignal-node
A Node.js client library for OneSignal API.
Table of Contents
- Overview
- Installation
- Usage
- Client Types
- Creating Client
- Create notification
- Cancel notification
- View notifications
- View notification
- View apps
- Create an app
- Update an app
- View devices
- View device
- Add a device
- Edit a device
- Edit tags with external user id
- New session
- New purchase
- Increment Session Length
- CSV Export
- Identity verification
- Tests
- Contributing
Overview
This is a wrapper library over OneSignal REST API. You can create notifications, view apps, edit a device and all other actions you can take on OneSignal REST API.
Installation
npm install onesignal-node --save
Usage
const OneSignal = require('onesignal-node'); OR
import * as OneSignal from 'onesignal-node'; Client Types:
For all the actions that require your OneSignal app id and app api key, you should use OneSignal.Client.
Sample actions: create notification, add device, csv export, create segment...
const client = new OneSignal.Client('appId', 'apiKey');For all the actions that require your User Auth Key you should use OneSignal.UserClient.
Sample actions: view apps, update an app, create an app...
const userClient = new OneSignal.UserClient('userAuthKey');Creating client
You can create a Client object as shown below. It requires two parameters: appId and apiKey, which you can find them on
your applications page on OneSignal dashboard.
There is also an optional parameter called options. You can set OneSignal rest api endpoint if you wish to using options.
By default the library uses https://onesignal.com/api/v1 for api endpoint.
// With default options
const client = new OneSignal.Client('appId', 'apiKey');
// With custom API endpoint
const client = new OneSignal.Client('appId', 'apiKey', { apiRoot: 'https://onesignal.com/api/v2'});Creating UserClient
You can create a UserClient object as shown below. It requires one parameter: userAuthKey, which you can find it on
your OneSignal dashboard.
There is also an optional parameter called options. You can set OneSignal rest api endpoint if you wish to using options.
By default the library uses https://onesignal.com/api/v1 for api endpoint.
// With default options
const userClient = new OneSignal.UserClient('userAuthKey');
// With custom API endpoint
const userClient = new OneSignal.UserClient('userAuthKey', { apiRoot: 'https://onesignal.com/api/v2'});Create notification
https://documentation.onesignal.com/reference/create-notification
.createNotification(body: CreateNotificationBody): Promise<ClientResponse>Please read the sections above to learn how to create a Client object.
// See all fields: https://documentation.onesignal.com/reference/create-notification
const notification = {
contents: {
'tr': 'Yeni bildirim',
'en': 'New notification',
},
included_segments: ['Subscribed Users'],
filters: [
{ field: 'tag', key: 'level', relation: '>', value: 10 }
]
};
// using async/await
try {
const response = await client.createNotification(notification);
console.log(response.body.id);
} catch (e) {
if (e instanceof OneSignal.HTTPError) {
// When status code of HTTP response is not 2xx, HTTPError is thrown.
console.log(e.statusCode);
console.log(e.body);
}
}
// or you can use promise style:
client.createNotification(notification)
.then(response => {})
.catch(e => {});Cancel notification
https://documentation.onesignal.com/reference/cancel-notification
.cancelNotification(notificationId: string): Promise<ClientResponse>const response = await client.cancelNotification('notification-id');
console.log(response.body);
console.log(response.headers);
console.log(response.statusCode); View notifications
https://documentation.onesignal.com/reference/view-notifications
.viewNotifications(query?: ViewNotificationsQuery): Promise<ClientResponse>// without query
const response = await client.viewNotifications();
console.log(response.body);
// with query
const response = await client.viewNotifications({ limit:10, kind: 2, offset: 2 });View notification
https://documentation.onesignal.com/reference/view-notification
.viewNotification(notificationId: string): Promise<ClientResponse>const response = await client.viewNotification('notification-id');
console.log(response.body); View apps
https://documentation.onesignal.com/reference/view-apps-apps
You should use UserClient for view apps since it requires User Auth Key
.viewApps(): Promise<ClientResponse>const response = await userClient.viewApps();
console.log(response.body);Create an app
https://documentation.onesignal.com/reference/create-an-app
You should use UserClient for view apps since it requires User Auth Key
.createApp(body: CreateAppBody): Promise<ClientResponse>const response = await userClient.createApp( { name: 'APP 1' });
console.log(response.body);Update an app
https://documentation.onesignal.com/reference/update-an-app
You should use UserClient for view apps since it requires User Auth Key
.updateApp(appId: string, body: UpdateAppBody): Promise<ClientResponse>const response = await userClient.updateApp( 'app-id',{ site_name: 'test' });
console.log(response.body);View devices
https://documentation.onesignal.com/reference/view-devices
.viewDevices(query?: LimitOffsetQuery): Promise<ClientResponse>const response = await client.viewDevices({ limit: 200, offset: 0 });
console.log(response.body);View device
https://documentation.onesignal.com/reference/view-device
.viewDevice(identifier: string): Promise<ClientResponse>const response = await client.viewDevice('device-id');
console.log(response.body);Add a device
https://documentation.onesignal.com/reference/add-a-device
.addDevice(body: AddDeviceBody): Promise<ClientResponse>const response = await client.addDevice({
device_type: 'ios',
identifier: 'id1',
});
console.log(response.body);Edit a device
https://documentation.onesignal.com/reference/edit-device
.editDevice(deviceId: string, body: EditDeviceBody): Promise<ClientResponse>const response = await client.editDevice('device-id',{
identifier: 'id2',
});
console.log(response.body);Edit tags with external user id
https://documentation.onesignal.com/reference/edit-tags-with-external-user-id
.editTagsWithExternalUserIdDevice(externalUserId: string, body: EditTagsBody): Promise<ClientResponse>const response = await client.editTagsWithExternalUserIdDevice('external-user-id', {
tags: {
customTag: "customValue"
},
});
console.log(response.body);New Session
https://documentation.onesignal.com/reference/new-session
.newSession(deviceId: string, body: NewSessionBody): Promise<ClientResponse>const response = await client.newSession('device-id',{
language: 'tr',
});
console.log(response.body);New Purchase
https://documentation.onesignal.com/reference/new-purchase
.newPurchase(deviceId: string, body: NewPurchaseBody): Promise<ClientResponse>const response = await client.newPurchase('device-id',{
purchases: [...],
});
console.log(response.body);Increment Session Length
https://documentation.onesignal.com/reference#increment-session-length
.incrementSessionLength(deviceId: string, body: IncrementSessionLengthBody): Promise<ClientResponse>const response = await client.incrementSessionLength('device-id',{
state: '',
active_time: 11,
});
console.log(response.body);CSV Export
https://documentation.onesignal.com/reference/csv-export
.exportCSV(body: ExportCSVBody): Promise<ClientResponse>const response = await client.exportCSV({});
console.log(response.body);Create Segment
https://documentation.onesignal.com/reference/create-segments
.createSegment(body: CreateSegmentBody): Promise<ClientResponse>const response = await client.createSegment({
name: 'new-segment',
filters: [..]
});
console.log(response.body);Delete Segment
https://documentation.onesignal.com/reference/delete-segments
.deleteSegment(segmentId: string): Promise<ClientResponse>const response = await client.deleteSegment('segment-id1');
console.log(response.body);Identity Verification
https://documentation.onesignal.com/docs/identity-verification
You can use these simple helpers to sign user id or email to be used in client-side code.
.signUserExternalId(id: string | number): string
.signUserEmail(email: string): stringEach of these will return SHA-256 hash, that was generated using apiKey.
Tests
Running all tests, coverage, build:
$ npm run test
$ npm run test-integration
$ npm run coverage
$ npm run build Contributing
TL;DR
To send a pull request:
- Fork the repo
- Clone the forked repo on your computer
- Switch to master branch
- Create a feature branch (
git checkout -b feature/new-feature-name) - Make your changes and add new tests if necessary
- Push your changes to your fork
- Open a pull request
License
This project is under the MIT license.