Skip to content

Latest commit

 

History

History
589 lines (462 loc) · 20.1 KB

README.md

File metadata and controls

589 lines (462 loc) · 20.1 KB
Raw

Welcome to @onesignal/node-onesignal 👋

Version Documentation Maintenance Twitter: onesignal

OpenAPI client for node-onesignal

🏠 Homepage

🖤 npm

Node Client SDK

The OneSignal Node client is a server OneSignal SDK for NodeJS. Integrate OneSignal with your backend events, data, and more.

Install

# yarn
yarn add @onesignal/node-onesignal

# npm
npm install @onesignal/node-onesignal --save

Usage

const OneSignal = require('@onesignal/node-onesignal');
import * as OneSignal from '@onesignal/node-onesignal';

Creating a client

Configuration

We can configure the client using the createConfiguration function. You can find more info on each configuration parameter here.

const configuration = OneSignal.createConfiguration(configParams);

Initializing the Client

const client = new OneSignal.DefaultApi(configuration);

Authentication

You can configure auth parameters passing them like this:

const configuration = OneSignal.createConfiguration({
    userAuthKey: '<YOUR_USER_AUTH_KEY>',
    restApiKey: '<YOUR_REST_API_KEY>',
});

const client = new OneSignal.DefaultApi(configuration);

Advanced Usage: Creating a brand-new app

If creating a new app via the client, the response will return the app's API key via the basic_auth_key response parameter. You can then use this to modify your configuration object and create a new client that will have both user-level and app-level authentication set up.

const response = await client.createApp(newapp);

const configuration = OneSignal.createConfiguration({
    userAuthKey: '<YOUR_USER_KEY_TOKEN>',
    restApiKey: response.basic_auth_key,
});

const client = new OneSignal.DefaultApi(configuration);

API Reference

See the full list of API Endpoints.

To make stateful changes requests should take on the following pattern:

  1. create or get an object
  2. make changes to that object
  3. pass the object to the request function to make the changes

Examples of important OneSignal objects include App, Notification, User, and Segment.

For example, see the section below on creating an app. First an app object is created via the instantiation of the App class. Then, the app instance is modified directly. Finally, we use the client to create the app via a remote request.

Creating an app

Creates a new OneSignal app.

Example

const app = new OneSignal.App();

// configure your application
app.name = 'app_name';
app.gcm_key = '<your key here>';
app.android_gcm_sender_id = '<your id here>';

const response = await client.createApp(app);

Getting an app

View the details of a single OneSignal app.

Example

const app = await client.getApp('<app id>');

Getting multiple apps

View apps.

Example

const apps = await client.getApps();

Updating an app

Updates the name or configuration settings of an existing OneSignal app.

Example

const app = new OneSignal.App();
app.name = 'modified_app_name';

const udpateAppResponse = await client.updateApp('<existing_app_id>', app);

Creating a notification

Sends a notification to your users.

Example

const notification = new OneSignal.Notification();
notification.app_id = app.id;
// Name property may be required in some case, for instance when sending an SMS.
notification.name = "test_notification_name";
notification.contents = {
  en: "Gig'em Ags"
}

// required for Huawei
notification.headings = {
  en: "Gig'em Ags"
}
const notification = await client.createNotification(notification);

Creating a notification using Filters

Sends a notification to your users filtered by specific criteria.

Example

const notification = new OneSignal.Notification();
notification.app_id = app.id;

notification.contents = {
  en: "Gig'em Ags"
}

// required for Huawei
notification.headings = {
  en: "Gig'em Ags"
}

// Find all the users that have not spent any amount in USD on IAP.
// https://documentation.onesignal.com/reference/create-notification#send-to-users-based-on-filters
notification.filters = [
    {
        field: 'amount_spent',
        relation: '=',
        value: "0"
    },
];

const notification = await client.createNotification(notification);

Canceling a notification

Stop a scheduled or currently outgoing notification.

Example

const cancelNotificationResponse = await client.cancelNotification('<app id>', '<notification id>');

Getting a notification

View the details of a single notification and outcomes associated with it.

Example

await client.getNotification('<app id>', '<notification id>');

Getting notifications

View the details of multiple notifications.

Param Type Description
app_id string The OneSignal App ID for your app. Available in Keys & IDs.
limit string How many notifications to return. Max is 50. Default is 50.
offset number Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at.
kind number Kind of notifications returned: * unset - All notification types (default) * 0 - Dashboard only * 1 - API only * 3 - Automated only

Example

const notifications = await client.getNotifications('<app id>', '50', 0, 1);

Getting notification history

View the devices sent a message - OneSignal Paid Plan Required This method will return all devices that were sent the given notification_id of an Email or Push Notification if used within 7 days of the date sent.

Example

const notificationHistory = await client.getNotificationHistory('<notification id>');

Creating a segment

Create segments visible and usable in the dashboard and API - Required: OneSignal Paid Plan

Example

const segment = new OneSignal.Segment();

segment.filters = [
  { field: 'session_count', relation: '&gt;', value: '1' },
  { field: 'tag', key: 'my_tag', relation: 'exists' }
]

const segment = await client.createSegments(app.id, segment);

Deleting a segment

Delete segments (not user devices) - Required: OneSignal Paid Plan You can delete a segment under your app by calling this API. You must provide an API key in the Authorization header that has admin access on the app. The segment_id can be found in the URL of the segment when viewing it in the dashboard.

Example

const deleteSegmentsResponse = await client.deleteSegments('<app id>', '<segment id>');

Creating a player

Add a device.

Example

const player = new OneSignal.Player();
player.device_type = 1;
player.app_id = app_id;
player.identifier = '<identifier>';
const player = await client.createPlayer(player);

Getting a player

View the details of an existing device in one of your OneSignal apps. The email and the hash is only required if you have enabled Identity Verification and device_type is email.

Example

const player = await client.getPlayer('<app id>', '<player id>', '<email auth hash>');

Getting players

View the details of multiple devices in one of your OneSignal apps.

⚠️ Unavailable for Apps Over 80,000 Users.

Param Type Description
app_id string The OneSignal App ID for your app. Available in Keys & IDs.
limit string How many devices to return. Max is 300. Default is 300
offset number Result offset. Default is 0. Results are sorted by id;

Example

const players = await client.getPlayers('<app id>', '300', 0);

Exporting a player

Generate a compressed CSV export of all of your current user data. This method can be used to generate a compressed CSV export of all of your existing user data and is a better alternative to retrieving this data using the /players API endpoint.

See full CSV Export Reference

Example

const exportPlayerResponse = await client.exportPlayer('<app id>', {
  extra_fields: ['location', 'external_user_id'],
  last_active_since: 1469392779,
  segment_name: "Subscribed Users"
});

Updating a player

Update an existing device in one of your OneSignal apps.

Example

const updatePlayerResponse = await client.updatePlayer('<player id>', player);

Updating player tags

Update an existing device's tags in one of your OneSignal apps using the External User ID.

const playerToUpdate = new OneSignal.Player();

player.app_id = APP_ID;
player.device_type = 1;

playerToUpdate.external_user_id = 'your_player_external_id'; // setting the same external_user_id as before
const updatePlayerTagsRequestBody = new OneSignal.UpdatePlayerTagsRequestBody();
updatePlayerTagsRequestBody.tags = {'typescript_test_tag': 1};
const updatePlayerResponse = await api.updatePlayerTags(APP_ID, PLAYER_EXTERNAL_USER_ID, updatePlayerTagsRequestBody);

Deleting Tags

To delete a tag, include its key and set its value to blank (""). Omitting a key/value will not delete it.

For example, if you wanted to delete two existing tags rank and category while simultaneously adding a new tag class, the tags JSON would look like the following:

Example

"tags": {
   "rank": "",
   "category": "",
   "class": "my_new_value"
}

Deleting a player

Deletes a user record.

Example

const deletePlayerResponse = await client.deletePlayer(app.id, '<player id>')

Getting outcomes

View the details of all the outcomes associated with your app.

🚧 Requires your OneSignal App's REST API Key, available in Keys & IDs 🚧

Outcome data are accessible for 30 days before being deleted from our servers. You can export this data monthly if you need it for a more extended period.

Param Type Description
app_id string The OneSignal App ID for your app. Available in Keys & IDs.
outcome_names string Required Comma-separated list of names and the value (sum/count) for the returned outcome data. Note: Clicks only support count aggregation. For out-of-the-box OneSignal outcomes such as click and session duration, please use the “os” prefix with two underscores. For other outcomes, please use the name specified by the user. Example:os__session_duration.count,os__click.count,CustomOutcomeName.sum
outcome_names2 string If outcome names contain any commas, then please specify only one value at a time. Example: outcome_names[]=os__click.count&outcome_names[]=Sales, Purchase.count where “Sales, Purchase” is the custom outcomes with a comma in the name.
outcome_time_range string Optional Time range for the returned data. The values can be 1h (for the last 1 hour data), 1d (for the last 1 day data), or 1mo (for the last 1 month data). Default is 1h if the parameter is omitted.
outcome_platforms string Optional Platform id. Refer device's platform ids for values. Example: outcome_platform=0 for iOS outcome_platform=7, 8 for Safari and Firefox Default is data from all platforms if the parameter is omitted.
outcome_attribution string Optional Attribution type for the outcomes. The values can be direct or influenced or unattributed. Example: outcome_attribution=direct Default is total (returns direct+influenced+unattributed) if the parameter is omitted.

Example

const outcomes = await client.getOutcomes(app.id, 'os__click.count,os_session_duration.count,my_outcome.sum');

Begin Live Activity

Starts a Live Activity event

// Create a player first
const player = new OneSignal.Player();
player.device_type = 0;
player.app_id = '<app id>';
const playerResponse = await api.createPlayer(player);

// Prepare a request
const beginLiveActivityRequest: BeginLiveActivityRequest = {
    push_token: '<push_token>',
    subscription_id: playerResponse.id!,
};
const activityId = '<activity_id>'; // any string

// Begin activity
await api.beginLiveActivity('<app_id>', activityId, beginLiveActivityRequest);

Update Live Activity

Updates a Live Activity event

const updateLiveActivityRequest: UpdateLiveActivityRequest = {
    event_updates: {
        data: 'test'
    },
    event: "update",
    name: "contents"
};

await api.updateLiveActivity('<app_id>', '<activity_id>', updateLiveActivityRequest);

End Live Activity

Stops a Live Activity event

const subscriptionId = '<subscription_id>'; // player id
await api.endLiveActivity('<app_id>', '<activity_id>', subscriptionId);

Subscription types

  • iOSPush
  • AndroidPush
  • FireOSPush
  • ChromeExtensionPush
  • ChromePush
  • WindowsPush
  • SafariLegacyPush
  • FirefoxPush
  • macOSPush
  • HuaweiPush
  • SafariPush
  • Email
  • SMS

Users

Creating a OneSignal User

const user = new OneSignal.User();

const aliasLabel = '<alias_label>';
const aliasId = '<alias_id>';
const subscriptionToken = '<subscription_token>';

user.identity = {
    [aliasLabel]: aliasId,
};

user.subscriptions = [
  {
    type: "iOSPush",
    token: subscriptionToken,
  }
];

const createdUser = await api.createUser('<app_id>', user);
assert(createdUser.identity!['onesignal_id'] != null);

Getting a user by onesignal_id

const oneisgnalAliasLabel = "onesignal_id";
const onesignalAliasId = createdUser.identity!['onesignal_id'];

const fetchedUser = await api.fetchUser('<app_id>', oneisgnalAliasLabel, onesignalAliasId);

Getting a user by an alias

const fetchedUser = await api.fetchUser('<app_id>', alias_label, alias_id);

Updating a user

const updateUserRequest: UpdateUserRequest = {
    properties: {
        language: 'fr'
    }
};

const updatedUser = await api.updateUser('<app_id>', aliasLabel, aliasId, updateUserRequest);

Deleting a user

await api.deleteUser('<app_id>', aliasLabel, aliasId);

Subscriptions

Creating a subscription for existing user

const createSubscriptionRequestBody: CreateSubscriptionRequestBody = {
    subscription: {
        type: "AndroidPush",
        token: '<subscription_token>',
    }
};

const response = await api.createSubscription('<app_id>', '<alias_label>', '<alias_id>', createSubscriptionRequestBody);

Updating a subscription

const updateSubscriptionRequestBody: UpdateSubscriptionRequestBody = {
    subscription: {
        type: "iOSPush",
        token: '<new-subscription-token>',
    }
};

await api.updateSubscription('<app_id>', '<existing_subscription_id>', updateSubscriptionRequestBody);

Deleting a subscription

await api.deleteSubscription('<app_id>', '<subscription_id>');

Transfer subscription ownership

Transfers the subscription from one user to another.

// Setting the user for transfering the subscription to. User is identyfied by an IdentityObject.
const transferSubscriptionRequestBody: TransferSubscriptionRequestBody = {
    identity: otherUserIdentityObject
};

const transferResponse = await api.transferSubscription('<app_id>', '<subscription_id>', transferSubscriptionRequestBody);

Aliases

Fetching aliases for a user

const fetchResponse = await api.fetchAliases('<app_id>', '<subscription_id>');

Fetching user identity

const fetchResponse = await api.fetchUserIdentity('<app_id>', '<alias_label>', '<alias_id>');

Identifying user by alias

const userIdentityRequestBody: UserIdentityRequestBody = {
    identity: {
        ['<new_alias_label>']: '<new_alias_id>'
    }
};

const identifyResponse = await api.identifyUserByAlias('<app_id>', 
                                                       '<existing_alias_label>', 
                                                       '<existing_alias_id>',
                                                       userIdentityRequestBody);

Identifying user by subscription id

const userIdentityRequestBody: UserIdentityRequestBody = {
    identity: {
        ['<new_alias_label>']: '<new_alias_id>'
    }
};

const identifyResponse = await api.identifyUserBySubscriptionId('<app_id>', '<existing_subscription_id>', userIdentityRequestBody);

Deleting an alias

await api.deleteAlias('<app_id>', '<alias_label>', '<alias_id>', '<alias_label_to_delete>');

Author

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page.

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2023 OneSignal.

This project is MIT licensed.