onesignal-sdk 2.0.0

A Python wrapper around the OneSignal API

onesignal_sdk

A Python client library for OneSignal REST API. Supports async/await.

Please read v1.x documentation for older versions.

Table of Contents

• Installation

• Example Usage

• Async Example Usage

• Handling Exceptions

• API methods

  • .send_notification
  • .cancel_notification
  • .view_notification
  • .view_notifications
  • .notification_history
  • .view_device
  • .view_devices
  • .add_device
  • .edit_device
  • .edit_tags
  • .new_session
  • .new_purchase
  • .csv_export
  • .create_segment
  • .delete_segment
  • .view_outcomes
  • .view_apps
  • .view_app
  • .create_app
  • .update_app

• License

Installation

pip install onesignal-sdk

Example Usage

You can think this library as a wrapper around OneSignal REST API. It is fairly simple to use:

• Create an instance of Client with your credentials. user_auth_key is not required but necessary for some API calls.
• Build your request body and call related method on the client.
• Client will make the request with required authentication headers and parse the response for you.

from onesignal_sdk.client import Client

client = Client(app_id=APP_ID, rest_api_key=REST_API_KEY, user_auth_key=USER_AUTH_KEY)

notification_body = {
    'contents': {'tr': 'Yeni bildirim', 'en': 'New notification'},
    'included_segments': ['Active Users'],
    'filters': [{'field': 'tag', 'key': 'level', 'relation': '>', 'value': 10}],
}
response = client.send_notification(notification_body)
print(response.body)

Async Example Usage

AsyncClient and Client shares exactly the same interface, method signatures. All the examples for Client in this documentation is also valid for AsyncClient.

from onesignal_sdk.client import AsyncClient

async def main():
    client = AsyncClient(app_id=APP_ID, rest_api_key=REST_API_KEY)

    notification_body = {'contents': ...}
    response = await client.send_notification(notification_body)
    print(response.body)

Handling Response

We are using httpx library for making http requests underneath. Responses from OneSignal REST API are parsed as JSON and returned to you as an instance of OneSignalResponse, which is just a simple class consisting of following attributes:

• .body: JSON parsed body of the response, as a Python dictionary.
• .status_code: HTTP status code of the response.
• .http_response: Original httpx.Response object, in case you want to access more attributes.

Sample code:

client = AsyncClient(...)
response = await client.view_apps()
print(response.body) # JSON parsed response
print(response.status_code) # Status code of response
print(response.http_response) # Original http response object.

Handling Exceptions

An instance of OneSignalHTTPError is raised whenever http responses have a status code other than 2xx. For instance, if status code of an http response is 404, OneSignalHTTPError is raised with additional details. See the sample snippet below, error handling is the same of AsyncClient

from onesignal_sdk.client import Client
from onesignal_sdk.error import OneSignalHTTPError

# Create a One Signal client using API KEYS.
client = Client(app_id=APP_ID, rest_api_key=REST_API_KEY, user_auth_key=USER_AUTH_KEY)
notification_body = {
    'contents': {'tr': 'Yeni bildirim', 'en': 'New notification'},
    'included_segments': ['Active Users'],
    'filters': [{'field': 'tag', 'key': 'level', 'relation': '>', 'value': 10}],
}
response = client.send_notification(notification_body)
print(response.body)

try:
    notification_body = {
        'contents': {'en': 'New notification'},
        'included_segments': ['Active Users'],
    }

    # Make a request to OneSignal and parse response
    response = client.send_notification(notification_body)
    print(response.body) # JSON parsed response
    print(response.status_code) # Status code of response
    print(response.http_response) # Original http response object.

except OneSignalHTTPError as e: # An exception is raised if response.status_code != 2xx
    print(e)
    print(e.status_code)
    print(e.http_response.json()) # You can see the details of error by parsing original response

API methods

send_notification

Reference: https://documentation.onesignal.com/reference/create-notification

notification_body = {
    'contents': {'en': 'New notification'},
    'included_segments': ['Active Users'],
}
response = client.send_notification(notification_body)

cancel_notification

Reference: https://documentation.onesignal.com/reference/cancel-notification

response = client.cancel_notification('notification-id')

view_notification

Reference: https://documentation.onesignal.com/reference/view-notification

response = client.view_notification('notification-id')

view_notifications

Reference: https://documentation.onesignal.com/reference/view-notifications

request_query = {'limit': 5, 'offset': 2}
response = client.view_notification(request_query)

notification_history

Reference: https://documentation.onesignal.com/reference/notification-history

body = {
    'events': 'clicked',
    'email': '[e-mail]'
}
response = client.notification_history('notification-id', body)

view_device

Reference: https://documentation.onesignal.com/reference/view-device

response = client.view_device('device-id')

view_devices

Reference: https://documentation.onesignal.com/reference/view-devices

request_query = {'limit': 1}
response = client.view_devices(request_query)

// or no query
response = client.view_devices()

add_device

Reference: https://documentation.onesignal.com/reference/add-a-device

body = {
    'device_type': 1,
    'identifier': '7a8bbbb00000'
}
response = client.add_device(body)

edit_device

Reference: https://documentation.onesignal.com/reference/edit-device

body = {
    'device_type': 1,
    'identifier': '7a8bbbb00000'
}
response = client.edit_device('2ada581e-1380-4967-bcd2-2bb4457d6171', body)

edit_tags

Reference: https://documentation.onesignal.com/reference/edit-tags-with-external-user-id

body = {
    'tags': {
        'foo': '',
        'bar': 'new_value',
    }
}
response = client.edit_tags('f0f0f0f0', body)

new_session

Reference: https://documentation.onesignal.com/reference/new-session

body = {
    'language': 'de',
    'timezone': -28800
}
response = client.new_session('foo-device-id', body)

new_purchase

Reference: https://documentation.onesignal.com/reference/new-purchase

body = {
    'purchases': [
        {'sku': 'SKU123', 'iso': 'EUR'}
    ]
}
response = client.new_purchase('foo-device-id', body)

csv_export

Reference: https://documentation.onesignal.com/reference/csv-export

body = {
    'extra_fields': ['country', 'location'],
    'last_active_since': '1469392779',
}
response = client.csv_export(body)

create_segment

Reference: https://documentation.onesignal.com/reference/create-segments

body = {
    'name': 'new-segment',
    'filters': [{'field': 'session_count', 'relation': '>', 'value': 1}],
}
response = client.create_segment(body)

delete_segment

Reference: https://documentation.onesignal.com/reference/delete-segments

response = client.delete_segment('segment-id-1')

view_outcomes

Reference: https://documentation.onesignal.com/reference/view-outcomes

extra_http_params = {
    'outcome_platforms': 0
}
outcome_names = ['os__click.count']
response = client.view_outcomes(outcome_names, extra_http_params)

view_apps

Reference: https://documentation.onesignal.com/reference/view-apps-apps

Requires user_auth_key!

response = client.view_apps()

view_app

Reference: https://documentation.onesignal.com/reference/view-an-app

Requires user_auth_key!

response = client.view_app('034744e7-4eb-1c6a647e47b')

create_app

Reference: https://documentation.onesignal.com/reference/create-an-app

Requires user_auth_key!

 app_body = {
    'name': 'new-android-app',
    'apns_env': 'production',
}
response = client.create_app(app_body)

update_app

Reference: https://documentation.onesignal.com/reference/update-an-app

Requires user_auth_key!

 app_body = {
    'name': 'new-app',
}
response = client.update_app('f33c318b-6c99', app_body)

License

This project is under the MIT license.