Crate a2

source ·
Expand description

§A2

A2 is an asynchronous client to Apple push notification service. It provides a type-safe way to generate correct requests, mapping responses into corresponding types. The client supports both, certificate and token based authentication.

To create a connection it is required to have either a PKCS12 database file including a valid certificate and private key with a password for unlocking it, or a private key in PKCS8 PEM format with the corresponding team and key ids. All of these should be available from Xcode or your Apple developer account.

§Payload

Building the notification payload should be done with the DefaultNotificationBuilder for most use-cases. There is also the WebNotificationBuilder in the case you need to send notifications to safari

The payload generated by the builder can hold a custom data section, defined by a selected root key. Any data using #[derive(Serialize)] from Serde works, allowing usage of type-safe structs or dynamic hashmaps to generate the custom data.

§Client

The asynchronous client, works either with certificate or token authentication.

§Example sending a plain notification using token authentication:

let mut builder = DefaultNotificationBuilder::new()
    .set_body("Hi there")
    .set_badge(420)
    .set_category("cat1")
    .set_sound("ping.flac");

let payload = builder.build("device-token-from-the-user", Default::default());
let mut file = File::open("/path/to/private_key.p8")?;

let client = Client::token(
    &mut file,
    "KEY_ID",
    "TEAM_ID",
    Endpoint::Production).unwrap();

let response = client.send(payload).await?;
println!("Sent: {:?}", response);

§Example sending a silent notification with custom data using certificate authentication:

#[macro_use] extern crate serde;

use a2::{
    Client, Endpoint, DefaultNotificationBuilder, NotificationBuilder, NotificationOptions,
    Priority,
};
use std::fs::File;

#[derive(Serialize, Debug)]
struct CorporateData {
    tracking_code: &'static str,
    is_paying_user: bool,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let tracking_data = CorporateData {
        tracking_code: "999-212-UF-NSA",
        is_paying_user: false,
    };

    let mut payload = DefaultNotificationBuilder::new()
        .set_content_available()
        .build("device-token-from-the-user",
        NotificationOptions {
            apns_priority: Some(Priority::Normal),
            ..Default::default()
        },
    );
    payload.add_custom_data("apns_gmbh", &tracking_data)?;

    let mut file = File::open("/path/to/cert_db.p12")?;

    let client = Client::certificate(
        &mut file,
        "Correct Horse Battery Stable",
        Endpoint::Production)?;

    let response = client.send(payload).await?;
    println!("Sent: {:?}", response);

    Ok(())
}

Re-exports§

Modules§

  • client
    The client module for sending requests and parsing responses
  • error
  • request
    The request payload module
  • response
    The APNs response types