Usage¶
Creating a client¶
A client is created from a aapns.api.Target
, which can be a
aapns.api.Server
when you want to interact with either production or development APNS, or a aapns.api.Simulator
if you want to send notifications to a simulator running on your machine.
A aapns.api.Target
has an asynchronous method
aapns.api.Target.create_client()
which returns a client class.
Client instances are supposed to be long-lived. Ideally you create one
instance when your app starts up and call the coroutine
aapns.api.APNSBaseClient.close()
at the end of your apps life
cycle. If your target is a server, the client will internally use a
connection pool to allow higher throughput.
APNS Client¶
The easiest way to create a client to talk to APNS is to use one of the
provided classmethods on aapns.api.Server
to either connect
to production APNS or development APNS, using the standard or
alternative port, aapns.api.Server.production()
,
aapns.api.Server.production_alt_port()
,
aapns.api.Server.development()
or
aapns.api.Server.development_alt_port()
, and then calling
aapns.api.Target.create_client()
on the returned Target.
All four methods take a single argument, the path to the client certificate to use as a string.
Simulator Client¶
To talk to a local simulator, create an instance of
aapns.api.Simulator
providing the simulator device ID and
app ID as arguments, then call the aapns.api.Target.create_client()
coroutine on that instance to create a client.
Sending Notifications¶
Once you have a client instance, you can send notifications by creating
instances of aapns.models.Notification
class.
In the most basic use case, pass it a aapns.models.Alert
object as
first argument. The aapns.models.Alert
requires at least a body
to be given. See API Reference for details about notifications and alerts.
Then call the coroutine aapns.api.APNSBaseClient.send_notification()
on your client providing the push token for your device and the
notification instance as arguments. For simulators the push token can be
any string. For more control over sending notifications, see the
documentation for the other arguments in API Reference.
Localization¶
The title and body of aapns.models.Alert
objects can be localized,
to do so use aapns.models.Localized
which takes the localization key
and an optional list of strings of localization arguments as arguments.
Putting it all together¶
Assuming we have our production certificate at /etc/apns.pem
and the device
we try to send a notification to has the device token adevicetoken
, we could
send it a hello world notification like this:
from aapns.api import Server
from aapns.models import Notification, Alert
async def send_hello_world():
client = await Server.production('/etc/apns.pem').create_client()
notification = Notification(
alert=Alert(
body='Hello World!'
)
)
await client.send_notification('adevicetoken', notification)
await client.close()
Command Line Client¶
For testing, aapns also includes a small command line client to send notifications.
To use it, you must install it using pip install aapns[cli]
. See
aapns --help
for usage information.