apns2 Python Library

Instead of using a certificate file, you can use Apple's token-based authentication (JWT) by passing TokenCredentials to the APNsClient. This requires your authentication key path, the key ID, and your Team ID.

from apns2.client import APNsClient
from apns2.payload import Payload
from apns2.credentials import TokenCredentials
import collections

# Authentication configuration
auth_key_path = 'path/to/auth_key'
auth_key_id = 'app_auth_key_id'
t team_id = 'app_team_id'

# Setup notification data
token_hex = 'b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b87'
payload = Payload(alert="Hello World!", sound="default", badge=1)
topic = 'com.example.App'
Notification = collections.namedtuple('Notification', ['token', 'payload'])
notifications = [Notification(payload=payload, token=token_hex)]

# Initialize client with TokenCredentials
token_credentials = TokenCredentials(auth_key_path=auth_key_path, auth_key_id=auth_key_id, team_id=team_id)
client = APNsClient(credentials=token_credentials, use_sandbox=False)

# Send batch
client.send_notification_batch(notifications=notifications, topic=topic)

Use send_notification to send a single push notification and wait for the result. This method will raise an exception if the notification fails to be accepted by APNs.

Parameters

• token_hex: The device token in hexadecimal format.
• notification: A Payload object containing the notification content.
• topic (optional): The apns-topic (usually the bundle ID).
• priority (optional): A NotificationPriority enum (Immediate or Delayed).
• expiration (optional): The expiration time in seconds.
• collapse_id (optional): The apns-collapse-id to group notifications.

from apns2.client import APNsClient
from apns2.payload import Payload
from apns2.credentials import CertificateCredentials

client = APNsClient(credentials=CertificateCredentials('cert.pem'))
payload = Payload(alert='Hello World')

client.send_notification(
    token_hex='DEVICE_TOKEN_HEX',
    notification=payload,
    topic='com.example.app'
)

The APNsClient is the primary interface for interacting with Apple Push Notification service (APNs). You can initialize it using either a Credentials object or a string path to a certificate file.

Parameters

• credentials: A Credentials instance or a str representing the path to a certificate file.
• use_sandbox (bool): If True, connects to the Apple development server (api.development.push.apple.com). Defaults to False (Live server).
• use_alternative_port (bool): If True, uses port 2197 instead of the default 443.
• heartbeat_period (float, optional): If provided, starts a background thread to send periodic pings to keep the connection alive.

from apns2.client import APNsClient
from apns2.credentials import CertificateCredentials

# Using a Credentials object
creds = CertificateCredentials('path/to/cert.pem', password='your_password')
client = APNsClient(credentials=creds, use_sandbox=True)

# OR using a certificate file path directly
client = APNsClient(credentials='path/to/cert.pem', password='your_password', use_sandbox=True)

To send multiple notifications efficiently, use send_notification_batch. This method leverages HTTP/2 streams to send multiple requests concurrently over a single connection, significantly improving throughput.

It automatically manages concurrency by reading the SETTINGS frame from the APNs server to determine the maximum allowed concurrent streams.

Parameters

• notifications: An iterable of Notification namedtuples, where each tuple contains (token, payload).
• topic, priority, expiration, collapse_id, push_type: Same as send_notification.

Returns

Returns a dictionary mapping each device token to its result. The result is either 'Success' or a string representing the failure reason (or a tuple (reason, timestamp) for Unregistered tokens).

from apns2.client import APNsClient, Notification
from apns2.payload import Payload
from apns2.credentials import CertificateCredentials

client = APNsClient(credentials=CertificateCredentials('cert.pem'))

# Create a list of Notification namedtuples
nots = [
    Notification(token='TOKEN_1', payload=Payload(alert='Msg 1')),
    Notification(token='TOKEN_2', payload=Payload(alert='Msg 2')),
]

results = client.send_notification_batch(notifications=nots, topic='com.example.app')

for token, result in results.items():
    print(f"Token {token} result: {result}")

Use the PayloadAlert class to define the visible content of a notification, such as the title, subtitle, and body text. It supports both direct strings and localization keys with arguments for multi-language support.

Parameters:

• title: The main title of the alert.
• title_localized_key: The localization key for the title.
• title_localized_args: A list of arguments for the title localization.
• subtitle: The subtitle of the alert.
• subtitle_localized_key: The localization key for the subtitle.
• subtitle_localized_args: A list of arguments for the subtitle localization.
• body: The main body text of the alert.
• body_localized_key: The localization key for the body text (maps to loc-key in the final dictionary).
• body_localized_args: A list of arguments for the body localization (maps to loc-args).
• action: The text for the action button.
• action_localized_key: The localization key for the action button.
• launch_image: A URL or path to a launch image.

from apns2.payload import PayloadAlert

alert = PayloadAlert(
    title="Hello",
    body="This is a notification",
    action="View"
)