APNs2 Python Library

Warnings

• breaking The library has a strict dependency on `PyJWT<2.0.0`. Installing or having other packages that require `PyJWT` version 2.0.0 or higher will lead to compatibility issues and runtime errors.
  Fix: Ensure your environment or `requirements.txt` explicitly specifies `PyJWT<2.0.0`. If other libraries demand `PyJWT>=2.0.0`, consider using a dedicated virtual environment or finding an alternative for APNs if upgrading `apns2` is not an option.
• breaking As of version 0.6.0, `apns2` officially dropped support for Python 2.7 and Python 3.4. Users on these Python versions must either upgrade their Python environment or use an older version of `apns2`.
  Fix: Upgrade your Python interpreter to Python 3.5 or newer.
• deprecated Apple officially deprecated the legacy binary APNs protocol (certificate-based authentication) on March 31, 2021, in favor of the HTTP/2 API with token-based authentication. While `apns2` supports both, new implementations and existing ones should migrate to token-based authentication.
  Fix: Switch to token-based authentication using `TokenCredentials` as shown in the quickstart example. This requires an authentication key (.p8 file), Key ID, and Team ID from your Apple Developer account.
• gotcha The default JWT token lifetime (`DEFAULT_TOKEN_LIFETIME`) was changed from 3600 seconds (1 hour) to 2700 seconds (45 minutes) in version 0.7.2. This aligns with Apple's recommendation to refresh tokens frequently (typically within one hour) to avoid `ExpiredProviderToken` errors. Additionally, in versions prior to 0.7.2, custom JWT lifetimes passed to `TokenCredentials` might have been ignored.
  Fix: Ensure your token generation logic and client configurations are aware of the shorter default lifetime. If you rely on custom JWT lifetimes, upgrade to 0.7.2 or newer to ensure they are respected.
• gotcha Since version 0.7.0, `apns2` attempts to infer the `apns-push-type` header from the push topic or payload. While an option to override this header exists, automatic inference might lead to unexpected behavior if specific push types are required without explicit setting.
  Fix: If precise control over the `apns-push-type` header is needed, explicitly set it in your `Payload` or `Notification` object when sending.

Install

• pip install apns2 Install latest version

Imports

• APNsClient

  from apns2.client import APNsClient

• Payload

  from apns2.payload import Payload

• TokenCredentials

  from apns2.credentials import TokenCredentials

Quickstart

This quickstart demonstrates sending a push notification using token-based authentication, which is recommended by Apple. Ensure you have your APNs authentication key (.p8 file), Key ID, Team ID, app bundle ID, and a target device token. These values are typically obtained from your Apple Developer account. It uses environment variables for sensitive credentials.

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

# Environment variables for token-based authentication
# Set these in your environment or replace with actual values for testing
AUTH_KEY_PATH = os.environ.get('APNS_AUTH_KEY_PATH', 'path/to/AuthKey_ABCDEFG.p8')
AUTH_KEY_ID = os.environ.get('APNS_AUTH_KEY_ID', 'ABCDEFG')
TEAM_ID = os.environ.get('APNS_TEAM_ID', 'XXXXXXXXXX')
DEVICE_TOKEN = os.environ.get('APNS_DEVICE_TOKEN', 'your_device_token_here')
APP_BUNDLE_ID = os.environ.get('APNS_APP_BUNDLE_ID', 'com.example.YourApp')

if AUTH_KEY_PATH == 'path/to/AuthKey_ABCDEFG.p8' or \
   AUTH_KEY_ID == 'ABCDEFG' or \
   TEAM_ID == 'XXXXXXXXXX' or \
   DEVICE_TOKEN == 'your_device_token_here' or \
   APP_BUNDLE_ID == 'com.example.YourApp':
    print("WARNING: Please configure APNS_AUTH_KEY_PATH, APNS_AUTH_KEY_ID, APNS_TEAM_ID, APNS_DEVICE_TOKEN, and APNS_APP_BUNDLE_ID environment variables or replace placeholders in the script.")
    # Exit or use dummy values for demonstration if actual push is not intended
    # For a runnable example without valid credentials, one might comment out the actual send_notification call
    # For this registry, we will print a warning and allow it to run potentially failing.

try:
    # Initialize TokenCredentials
    credentials = TokenCredentials(
        auth_key_path=AUTH_KEY_PATH,
        auth_key_id=AUTH_KEY_ID,
        team_id=TEAM_ID
    )

    # Initialize APNsClient with token credentials
    # For development (sandbox) environment, use_sandbox=True
    client = APNsClient(credentials=credentials, use_sandbox=True) # Set to False for production

    # Create a push notification payload
    payload = Payload(alert="Hello from apns2!", sound="default", badge=1)

    # Send the notification
    response = client.send_notification(DEVICE_TOKEN, payload, APP_BUNDLE_ID)

    print(f"APNs Response Status: {response.status}")
    print(f"APNs Response Reason: {response.reason}")
    if response.apns_id: # Optional, depending on library version/response structure
        print(f"APNs ID: {response.apns_id}")

except Exception as e:
    print(f"An error occurred: {e}")