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): string

Each 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.