kvandake / onesignal

Typescript client for OneSignal Server Rest API

OneSignal API Client

Features

• Written in Typescript.
• The code is covered by tests.
• The library uses Axios.
• Two clients for different method calls: OneSignalAppClient, OneSignalUserClient. OneSignalAppClient is created for notifications, devices, tracks or sessions. OneSignalUserClient is created for apps.
• Support create a notification builder. You may target users in one of three ways using this builders: by NotificationBySegmentBuilder, by NotificationByFilterBuilder, or by NotificationByDeviceBuilder.
• Support methods for different contents: Notification or Email. Support methods is available in the builders.

Getting Started

Npm

npm install onesignal-api-client-core

Yarn

yarn add onesignal-api-client-core

Using

Create notification

The Create Notification method is used when you want your server to programmatically send notifications or emails to a segment or individual users. You may target users in one of three ways using this method: by Segment, by Filter, or by Device. At least one targeting parameter must be specified.

Create notification through the Segment

API Reference Segments are the most common way developers send notifications via OneSignal. Sending to segments is easy: you simply specify which segments you want to send to, and, optionally, which ones you don't.

import { OneSignalAppClient, NotificationBySegmentBuilder } from 'onesignal-api-client-core';

const client = new OneSignalAppClient('appId', 'restApiKey');

const input = new NotificationBySegmentBuilder()
    .setIncludedSegments(['Active Users', 'Inactive Users'])
    .notification() // .email()
    .setContents({ en: 'My Message' })
    .build();

const result = await client.createNotification(input);

Create notification through the Filter

API Reference Filters are a powerful way to target users, allowing you to use both data that OneSignal has about a user and any Tags your app may send OneSignal. Filters can be combined together to form advanced, highly precise user targeting. OneSignal customers use all sorts of filters to send notifications, including language, location, user activity, and more.

import { OneSignalAppClient, NotificationByFilterBuilder } from 'onesignal-api-client-core';

const client = new OneSignalAppClient('appId', 'restApiKey');

const filters = [
    { 'field': 'tag', 'key': 'level', 'relation': '>', 'value': '10' },
    { 'field': 'amount_spent', 'relation': '>', 'value': '0' },
];
const input = new NotificationByFilterBuilder()
    .setFilters(filters)
    .notification() // .email()
    .setContents({ en: 'My Message' })
    .build();

const result = await client.createNotification(input);

Create notification through the Device

API Reference You may also target specific devices with the create notification method. Targeting devices is typically used in two ways:

• For notifications that target individual users, such as if they've received a message from someone.
• For apps that wish to manage their own segments, such as tracking a user's followers and sending notifications to them when that user posts.

import { OneSignalAppClient, NotificationByDeviceBuilder } from 'onesignal-api-client-core';

const client = new OneSignalAppClient('appId', 'restApiKey');

const input = new NotificationByDeviceBuilder()
    .setIncludeExternalUserIds(['externalUserId1', 'externalUserId2'])
    .notification() // .email()
    .setContents({ en: 'My Message' })
    .build();

const result = await client.createNotification(input);

Cancel notification

API Reference Stop a scheduled or currently outgoing notification.

import { OneSignalAppClient, ICancelNotificationInput } from 'onesignal-api-client-core';

const client = new OneSignalAppClient('appId', 'restApiKey');

const input = { id: notification.id } as ICancelNotificationInput;
const result = await client.cancelNotification(input);

Create, View or Update a Device

API Reference

import { OneSignalAppClient, ICreateDeviceInput, IViewDeviceInput, IUpdateDeviceInput, DeviceType } from 'onesignal-api-client-core';

const client = new OneSignalAppClient('appId', 'restApiKey');

const createInput = { device_type: DeviceType.ChromeWebPush } as ICreateDeviceInput;
const createResult = await client.createDevice(input);

const viewInput = { id: device.id } as IViewDeviceInput;
const viewResult = await client.viewDevice(viewInput);
const viewsResult = await client.viewDevices();

const updateInput = { id: device.id, device_type: DeviceType.Android } as IUpdateDeviceInput;
const updateResult = await client.updateDevice(input);

Create, View or Update an OneSignal App

API Reference

import { OneSignalUserClient, ICreateAppInput, IViewAppInput, IUpdateAppInput } from 'onesignal-api-client-core';

const client = new OneSignalUserClient('userAuthKey');

const createInput = { name } as ICreateAppInput;
const createResult = await client.createApp(input);

const viewInput = { id: app.id } as IViewAppInput;
const viewResult = await client.viewApp(viewInput);
const viewsResult = await client.viewApps();

const updateInput = { id: app.id, name: 'Updated name' } as IUpdateAppInput;
const updateResult = await client.updateApp(input);

Track open

API Reference

import { OneSignalAppClient, ITrackOpenInput } from 'onesignal-api-client-core';

const client = new OneSignalAppClient('appId', 'restApiKey');

const trackOpenInput = { notificationId: notification.id, opened: true } as ITrackOpenInput;
const trackOpenResult = await client.trackOpen(input);

New Session

API Reference

import { OneSignalAppClient, INewSessionInput } from 'onesignal-api-client-core';

const client = new OneSignalAppClient('appId', 'restApiKey');

const newSessionInput = { deviceId: device.id } as INewSessionInput;
const newSessionResult = await client.newSession(input);

OneSignal server implementation methods

List of server api methods.

• Create notification
• Cancel notification
• View apps
• View an app
• Create an app
• Update an app
• View devices
• View device
• Add a device
• Edit device
• New session
• New purchase
• Increment session length
• CSV export
• View notification
• View notifications
• Track open
• Notification History
• Create Segments
• Delete Segments

Support

If any bugs are found in the API wrapper, please open an issue on GitHub, or a Pull Request if you want to fix it yourself! Please be as explicit as possible and provide a minimum reproducing repository if at all possible, as it helps track down what went wrong.

Documentation

All documentation for this wrapper comes from the Server Rest API, if there are any typos, please let me know or open a PR to fix it.

TODO

• Implements all methods

Licence

MIT

onesignal's Issues

I can't send a notification with image

I'm adding this into my node app and trying to send a notification with image, it says has been send and delivered, but it doesn't on my device.

That's happened only when trying to add a big_picture with the notification!! ( some times I receive a notification like 2 from 10 after 10 min or so but with no image which is weird as I even checked from the pannel it says the notification has an image with it )

So my code looks like this:

@Cron('45 * * * * *')
async sendNotificaiotns() {
    console.log('sending notification');

    try {
        const randomArticle = await this.articleRepository
            .createQueryBuilder()
            .orderBy("RAND()")
            .limit(1)
            .getOne();

        const input = new NotificationBySegmentBuilder()
            .setIncludedSegments(['Active Users', 'Inactive Users'])
            .notification() // .email()
            .setAttachments({
                data: {
                    randomArticle,
                },
                big_picture: encodeURI(randomArticle.image)
            })
            .setHeadings({ 'en': randomArticle.title })
            .setContents({'en': randomArticle.title })
            .build();

        console.log(randomArticle);
        await this.oneSignalService.createNotification(input);

    } catch (e) {
        console.log(e);
    }
}

Update vulnerable dependencies

Please update dependencies, especially axios

Thanks