Skip to main content

A Python wrapper around the OneSignal API

Project description

onesignal_sdk

https://img.shields.io/pypi/pyversions/onesignal-sdk.svg https://img.shields.io/pypi/v/onesignal-sdk.svg https://travis-ci.com/zeyneloz/onesignal_sdk.svg?branch=master https://codecov.io/gh/zeyneloz/onesignal_sdk/branch/master/graph/badge.svg

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

Please read v1.x documentation for older versions.

Table of Contents

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': 'test@email.com'
}
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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

onesignal-sdk-2.0.0.tar.gz (15.8 kB view details)

Uploaded Source

Built Distribution

onesignal_sdk-2.0.0-py3-none-any.whl (16.5 kB view details)

Uploaded Python 3

File details

Details for the file onesignal-sdk-2.0.0.tar.gz.

File metadata

  • Download URL: onesignal-sdk-2.0.0.tar.gz
  • Upload date:
  • Size: 15.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/49.2.0 requests-toolbelt/0.9.1 tqdm/4.48.0 CPython/3.8.0

File hashes

Hashes for onesignal-sdk-2.0.0.tar.gz
Algorithm Hash digest
SHA256 c6d1646e52f6ea2c13b45800af42b339ea2514e918baffe8a9894c6539cdaff7
MD5 4aacaa3af42d67b6b9423e22ecbb3113
BLAKE2b-256 65b3b51bd48174ed190daab28a70afa1ef27db61f8145a7fbc7cfd2a0815c039

See more details on using hashes here.

File details

Details for the file onesignal_sdk-2.0.0-py3-none-any.whl.

File metadata

  • Download URL: onesignal_sdk-2.0.0-py3-none-any.whl
  • Upload date:
  • Size: 16.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/49.2.0 requests-toolbelt/0.9.1 tqdm/4.48.0 CPython/3.8.0

File hashes

Hashes for onesignal_sdk-2.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 be2815178b71e5ece0d6cb1be348d496c8a14e65bfbc1e82cdd1b0d4dae63187
MD5 ed57ea2ce219943f0fe5e165f3c3a3cb
BLAKE2b-256 e55ee432d308784ea9723d6a2ae9d6a3df18b5b3723dd6e30a6e1101cd41050d

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page