Skip to content

Commit 22e83c3

Browse files
author
Rodrigo Gomez Palacio
authored
Merge pull request #3 from OneSignal/beta2-release
Beta2 release
2 parents 54b7270 + 9f858cd commit 22e83c3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

57 files changed

+9414
-0
lines changed

‎README.md

Lines changed: 317 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,317 @@
1+
# Overview
2+
This is a Node.js 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. Includes Typescript support.
3+
4+
# Installation
5+
6+
```
7+
npm install @onesignal/node-onesignal --save
8+
```
9+
10+
```
11+
yarn add @onesignal/node-onesignal
12+
```
13+
14+
# Usage
15+
```js
16+
const OneSignal = require('@onesignal/node-onesignal');
17+
```
18+
```js
19+
import * as OneSignal from '@onesignal/node-onesignal';
20+
```
21+
22+
## Creating a client
23+
### Configuration
24+
We can configure the client using the `createConfiguration` function. You can find more info on each configuration parameter [here](https://github.com/OpenAPITools/openapi-generator/pull/10283/files).
25+
26+
```js
27+
const configuration = OneSignal.createConfiguration(configParams);
28+
```
29+
The returned `configuration` object is what is passed to the `DefaultApi` constructor to initialize the client.
30+
31+
### Initializing the Client
32+
```js
33+
const client = new OneSignal.DefaultApi(configuration);
34+
```
35+
36+
### Authentication
37+
#### User
38+
For managing operations outside of a OneSignal app (e.g: creating a OneSignal app), you will need to use your OneSignal account [user auth key](https://documentation.onesignal.com/docs/accounts-and-keys#user-auth-key). Create a key provider object with a function `getToken` that returns your key.
39+
```js
40+
const user_key_provider = {
41+
getToken() {
42+
return "************************************************";
43+
}
44+
};
45+
```
46+
47+
#### App
48+
Create a key provider object with a function `getToken` that returns your OneSignal [app's API key](https://documentation.onesignal.com/docs/accounts-and-keys#rest-api-key).
49+
50+
```js
51+
const app_key_provider = {
52+
getToken() {
53+
return "************************************************";
54+
}
55+
};
56+
```
57+
58+
#### Putting it together
59+
```js
60+
// configuration object
61+
let configuration = OneSignal.createConfiguration({
62+
authMethods: {
63+
user_key: {
64+
tokenProvider: user_key_provider
65+
},
66+
app_key: {
67+
tokenProvider: app_key_provider
68+
}
69+
}
70+
});
71+
72+
client = new OneSignal.DefaultApi(configuration);
73+
```
74+
75+
#### Advanced Usage: Creating a brand new app
76+
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.
77+
78+
```js
79+
let response = await client.createApp(newapp);
80+
const app_key_provider = {
81+
getToken() {
82+
return response.basic_auth_key;
83+
}
84+
};
85+
86+
configuration = OneSignal.createConfiguration({
87+
authMethods: {
88+
user_key: {
89+
tokenProvider: user_key_provider
90+
},
91+
app_key: {
92+
tokenProvider: app_key_provider
93+
}
94+
}
95+
});
96+
97+
client = new OneSignal.DefaultApi(configuration);
98+
```
99+
100+
---
101+
## API Reference
102+
To understand this API, know that requests that change state will follow the following format:
103+
1. create or get an object
104+
2. make changes to that object
105+
3. pass the object to the request function to make the changes.
106+
107+
Examples of important OneSignal objects include `App`, `Notification`, `Player`, and `Segment`.
108+
109+
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.
110+
111+
### Creating an app
112+
Creates a new OneSignal app.
113+
114+
**Example**
115+
```js
116+
const app = new OneSignal.App();
117+
118+
// configure your application
119+
app.name = 'app_name';
120+
app.gcm_key = '<your key here>';
121+
app.android_gcm_sender_id = '<your id here>';
122+
123+
const response = await client.createApp(app);
124+
```
125+
126+
### Getting an app
127+
View the details of a single OneSignal app.
128+
129+
**Example**
130+
```js
131+
client.getApp('<app id>');
132+
```
133+
134+
### Updating an app
135+
Updates the name or configuration settings of an existing OneSignal app.
136+
137+
**Example**
138+
```js
139+
client.updateApp('<app id>', app);
140+
```
141+
142+
### Creating a notification
143+
Sends a notification to your users.
144+
145+
**Example**
146+
```js
147+
const notification = new OneSignal.Notification();
148+
notification.app_id = app.id;
149+
150+
notification.contents = {
151+
en: "Gig'em Ags"
152+
}
153+
154+
// required for Huawei
155+
notification.headings = {
156+
en: "Gig'em Ags"
157+
}
158+
client.createNotification(notification);
159+
```
160+
161+
### Getting a notification
162+
View the details of a single notification and outcomes associated with it.
163+
164+
**Example**
165+
```js
166+
client.getNotification('<app id>', '<notification id>');
167+
```
168+
169+
### Getting notifications
170+
View the details of multiple notifications.
171+
172+
| Param | Type | Description |
173+
|--------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
174+
| app_id* | string | The OneSignal App ID for your app. Available in Keys &amp; IDs. |
175+
| limit | string | How many notifications to return. Max is 50. Default is 50. |
176+
| 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. |
177+
| kind | number | Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only |
178+
179+
180+
**Example**
181+
```js
182+
client.getNotifications('<app id>', '50', 0, 1);
183+
```
184+
185+
### Getting notification history
186+
View the devices sent a message - **OneSignal Paid Plan Required**
187+
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.
188+
189+
**Example**
190+
```js
191+
client.getNotificationHistory('<notification id>');
192+
```
193+
194+
### Creating a segment
195+
Create segments visible and usable in the dashboard and API - **Required: OneSignal Paid Plan**
196+
197+
**Example**
198+
```js
199+
const segment = new OneSignal.Segment();
200+
201+
segment.filters = [
202+
{ field: 'session_count', relation: '&gt;', value: '1' },
203+
{ field: 'tag', key: 'my_tag', relation: 'exists' }
204+
]
205+
206+
client.createSegments(app.id, segment)
207+
```
208+
209+
### Deleting a segment
210+
Delete segments (not user devices) - **Required: OneSignal Paid Plan**
211+
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.
212+
The `segment_id` can be found in the URL of the segment when viewing it in the dashboard.
213+
214+
**Example**
215+
```js
216+
client.deleteSegments('<app id>', '<segment id>');
217+
```
218+
219+
### Getting a player
220+
View the details of an existing device in one of your OneSignal apps. The email a th hash is **only required if you have enabled Identity Verification and `device_type` is email**.
221+
222+
**Example**
223+
```js
224+
client.getPlayer('<app id>', '<player id>', '<email auth hash>');
225+
```
226+
227+
### Getting players
228+
View the details of multiple devices in one of your OneSignal apps. Unavailable for Apps Over 80,000 Users.
229+
230+
| Param | Type | Description |
231+
|---------|--------|------------------------------------------------------------------|
232+
| app_id* | string | The OneSignal App ID for your app. Available in Keys &amp; IDs. |
233+
| limit | string | How many devices to return. Max is 300. Default is 300 |
234+
| offset | number | Result offset. Default is 0. Results are sorted by id; |
235+
236+
237+
**Example**
238+
```js
239+
client.getPlayers('<app id>', '300', 0);
240+
```
241+
242+
### Exporting a player
243+
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 current user data. It is a much faster alternative than retrieving this data using the /players API endpoint.
244+
245+
See [full CSV Export Reference](https://documentation.onesignal.com/reference/csv-export)
246+
247+
**Example**
248+
```js
249+
client.exportPlayer('<app id>', {
250+
extra_fields: ['location', 'external_user_id'],
251+
last_active_since: 1469392779,
252+
segment_name: "Subscribed Users"
253+
});
254+
```
255+
256+
257+
### Updating a player
258+
Update an existing device in one of your OneSignal apps.
259+
260+
**Example**
261+
```js
262+
client.updatePlayer('<player id>', player);
263+
```
264+
265+
### Updating player tags
266+
Update an existing device's tags in one of your OneSignal apps using the External User ID.
267+
#### Warning - Android SDK Data Synchronization
268+
Tags added through the Android SDK tagging methods may not update if using the API to change or update the same tag.
269+
For example, if you use SDK method sendTag("key", "value1") then update the tag value to "value2" with this API endpoint. You will not be able to set the value back to "value1" through the SDK, you will need to change it to something different through the SDK to be reset.
270+
271+
Recommendations if using this Endpoint on Android Mobile Apps:
272+
1 - Do not use the same tag keys for SDK and API updates
273+
2 - If you want to use the same key for both SDK and API updates, call the SDK getTags method first to update the device's tags.
274+
275+
This is only applicable on the Android Mobile App SDKs.
276+
277+
#### Deleting Tags
278+
To delete a tag, include its key and set its value to blank. Omitting a key/value will not delete it.
279+
For example, if I wanted to delete two existing tags rank and category while simultaneously adding a new tag class, the tags JSON would look like the following:
280+
281+
**Example**
282+
```json
283+
"tags": {
284+
"rank": "",
285+
"category": "",
286+
"class": "my_new_value"
287+
}
288+
```
289+
290+
### Deleting a player
291+
Delets a user record.
292+
293+
**Example**
294+
```js
295+
client.deletePlayer(app.id, '<player id>')
296+
```
297+
298+
### Getting outcomes
299+
View the details of all the outcomes associated with your app.
300+
301+
🚧 **Requires Authentication Key Requires your OneSignal App's REST API Key, available in Keys & IDs** 🚧
302+
303+
Outcome Data Limitations Outcomes are only accessible for around 30 days before deleted from our servers. You will need to export this data every month if you want to keep it.
304+
305+
| Param | Type | Description |
306+
|---------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
307+
| app_id* | string | The OneSignal App ID for your app. Available in Keys &amp; IDs. |
308+
| 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 |
309+
| 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. |
310+
| 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. |
311+
| outcome_platforms | string | Optional Platform id. Refer device&#39;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. |
312+
| 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. |
313+
314+
**Example**
315+
```js
316+
client.getOutcomes(app.id, 'os__click.count,os_session_duration.count,my_outcome.sum');
317+
```

0 commit comments

Comments
 (0)