A Python wrapper around the OneSignal API
Project description
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
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)
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
Built Distribution
Hashes for onesignal_sdk-2.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | be2815178b71e5ece0d6cb1be348d496c8a14e65bfbc1e82cdd1b0d4dae63187 |
|
MD5 | ed57ea2ce219943f0fe5e165f3c3a3cb |
|
BLAKE2b-256 | e55ee432d308784ea9723d6a2ae9d6a3df18b5b3723dd6e30a6e1101cd41050d |