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.
The library is meant to be high performace and typesafe, used together with the Tokio framework in an asynchronous event loop.
Payload
Building the notification payload should be done with the corresponding builders:
- PlainNotificationBuilder for text only messages.
- SilentNotificationBuilder for silent notifications with custom data.
- LocalizedNotificationBuilder for localized rich notifications.
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:
extern crate tokio;
extern crate a2;
extern crate futures;
use a2::{PlainNotificationBuilder, NotificationBuilder, Client, Endpoint};
use std::fs::File;
use futures::future::lazy;
use futures::Future;
fn main() {
let mut builder = PlainNotificationBuilder::new("Hi there");
builder.set_badge(420);
builder.set_category("cat1");
builder.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").unwrap();
let client = Client::token(
&mut file,
"KEY_ID",
"TEAM_ID",
Endpoint::Production).unwrap();
tokio::run(lazy(move || {
client
.send(payload)
.map(|response| {
println!("Sent: {:?}", response);
})
.map_err(|error| {
println!("Error: {:?}", error);
})
}));
}
Example sending a silent notification with custom data using certificate authentication:
#[macro_use] extern crate serde_derive;
extern crate serde;
extern crate tokio;
extern crate a2;
extern crate futures;
use a2::{Client, Endpoint, SilentNotificationBuilder, NotificationBuilder};
use std::fs::File;
use futures::future::lazy;
use futures::Future;
#[derive(Serialize, Debug)]
struct CorporateData {
tracking_code: &'static str,
is_paying_user: bool,
}
fn main() {
let tracking_data = CorporateData {
tracking_code: "999-212-UF-NSA",
is_paying_user: false,
};
let mut payload = SilentNotificationBuilder::new()
.build("device-token-from-the-user", Default::default());
payload.add_custom_data("apns_gmbh", &tracking_data).unwrap();
let mut file = File::open("/path/to/cert_db.p12").unwrap();
let client = Client::certificate(
&mut file,
"Correct Horse Battery Stable",
Endpoint::Production).unwrap();
let sending = client.send(payload);
tokio::run(lazy(move || {
sending
.map(|response| {
println!("Sent: {:?}", response);
})
.map_err(|error| {
println!("Error: {:?}", error);
})
}));
}
Re-exports
pub use request::notification::NotificationBuilder;
pub use response::Response;
pub use response::ErrorBody;
pub use response::ErrorReason;
pub use client::Endpoint;
pub use client::Client;
pub use client::FutureResponse;
pub use error::Error;
Modules
Structs
Serialize
from Serde.