Apple Push Notification Service (APNS) API.
Behaviours: supervisor.
Authors: Edwin Fine (efine@silentcircle.com).
This is the API to the Apple Push Notification Service Provider.
See apns_erlv3_session for a description of Opts.
Opts = [
{name, 'apnsv3-com.example.FakeApp.voip'},
{token, "ca6a7fef1...4f1dc2"},
{config,
[
{host, <<"api.development.push.apple.com">>},
{port, 443},
{apns_env, prod},
{apns_topic, <<"com.example.FakeApp.voip">>},
{app_id_suffix, <<"com.example.FakeApp.voip">>},
{team_id, <<"6F44JJ9SDF">>},
{disable_apns_cert_validation, true},
{ssl_opts, [
{cacertfile, "/etc/ssl/certs/ca-certificates.crt"},
{certfile, "com.example.FakeApp.cert.pem"},
{keyfile, "com.example.FakeApp.key.pem"},
{verify, verify_peer},
{honor_cipher_order, false},
{versions, ['tlsv1.2']},
{alpn_advertised_protocols, [<<"h2">>]}]}
]}
],
{ok, Pid} = sc_push_svc_apnsv3:start_session(my_push_tester, Opts).
Notification = [{alert, Alert}, {token, <<"e7b300...a67b">>}],
{ok, ParsedResp} = sc_push_svc_apnsv3:send(my_push_tester, Notification).
JSON = get_json_payload(), % See APNS docs for format
Nf = [{token, Token}, {json, JSON}],
{ok, ParsedResp} = apns_erlv3_session:send(my_push_tester, Nf).
ok = sc_push_svc_apnsv3:stop_session(my_push_tester).
alert_prop() = {title, binary()} | {body, binary()} | {'title-loc-key', binary() | null} | {'title-loc-args', [binary()] | null} | {'action-loc-key', binary() | null} | {'loc-key', binary()} | {'loc-args', [binary()]} | {'launch-image', binary()}
alert_proplist() = [alert_prop()]
async_send_opt() = {from_pid, pid()} | {callback, apns_erlv3_session:send_callback()}
async_send_opts() = [async_send_opt()]
async_send_reply() = apns_erlv3_session:async_send_reply()
fsm_ref() = apns_erlv3_session:fsm_ref()
gen_proplist() = sc_types:proplist(atom(), term())
nf_prop() = {alert, binary() | alert_proplist()} | {badge, integer()} | {sound, binary()} | {'content-available', 0 | 1} | {category, binary()} | {extra, apns_json:json_term()}
notification() = [nf_prop()]
session() = [session_opt()]
session_config() = apns_erlv3_session:options()
session_opt() = {name, atom()} | {mod, atom()} | {config, session_config()}
sessions() = [session()]
sync_send_reply() = apns_erlv3_session:sync_send_reply()
| async_send/2 | Equivalent to async_send(Name, Notification, []). |
| async_send/3 | Asynchronously sends a notification specified by proplist
Notification to Name with proplist Opts. |
| send/2 | Equivalent to send(Name, Notification, []). |
| send/3 | Send a notification specified by proplist Notification
to Name with options Opts (currently unused). |
| start_link/1 | Sessions is a list of proplists. |
| start_session/2 | Start named session for specific host and certificate as
supplied in the proplist Opts. |
| stop_session/1 | Stop named session. |
async_send(Name, Notification) -> Result
Name = fsm_ref()Notification = notification()Result = async_send_reply()
Equivalent to async_send(Name, Notification, []).
async_send(Name, Notification, Opts) -> Result
Name = fsm_ref()Notification = notification()Opts = async_send_opts()Result = async_send_reply()
Asynchronously sends a notification specified by proplist
Notification to Name with proplist Opts.
Returns {ok, Result} or {error, term()}, where Result can be either
{queued, uuid()} or {submitted, uuid()}. The difference between
queued and submitted is the HTTP/2 session connection status. If the
HTTP/2 session is connected at the time the request is made, submitted
is used. If the session is not connected, the request is queued internally
until the session connects and queued is used to show this.
It is possible that a queued notification could be lost if the session dies before it can connect to APNS.
Opts is a proplist that can take the following properties.
{from_pid, pid()}pid that will be passed to the callback function as the from
property of the notification proplist (the first parameter of the
callback function). If omitted, the pid is set to self(). It will
be ignored unless the callback property is also provided.{callback, apns_erlv3_session:send_callback()}from_pid - if provided - is ignored.The callback function type signature is
apns_erlv3_session:send_callback(). The parameters
are described in apns_erlv3_session:async_send_cb/4.
fun(NfPL, Req, Resp) -> any().
-
NfPLis the notification proplist as received by the session. -
Reqis the HTTP/2 request as sent to APNS. -
Respis the HTTP/2 response received from APNS, parsed into a proplist.
-spec example_callback(NfPL, Req, Resp) -> ok when
NfPL :: apns_erlv3_session:send_opts(),
Req :: apns_erlv3_session:cb_req(),
Resp :: apns_erlv3_session:cb_result().
example_callback(NfPL, Req, Resp) ->
case proplists:get_value(from, NfPL) of
Caller when is_pid(Caller) ->
UUID = proplists:get_value(uuid, NfPL),
Caller ! {user_defined_cb, #{uuid => UUID,
nf => NfPL,
req => Req,
resp => Resp}},
ok;
undefined ->
log_error("Cannot send result, no caller info: ~p", [NfPL])
end.
NfPL = [{uuid,<<"44e83e09-bfb6-4f67-a281-f437a7450c1a">>},
{expiration,2147483647},
{token,<<"de891ab30fc96af54406b22cfcb2a7da09628c62236e374f044bd49879bd8e5a">>},
{topic,<<"com.example.FakeApp.voip">>},
{json,<<"{\"aps\":{\"alert\":\"Hello, async user callback\"}}">>},
{from,<0.1283.0>},
{priority,undefined}].
Req = {[{<<":method">>,<<"POST">>},
{<<":path">>, <<"/3/device/de891ab30fc96af54406b22cfcb2a7da09628c62236e374f044bd49879bd8e5a">>},
{<<":scheme">>,<<"https">>},
{<<"apns-topic">>, <<"com.example.FakeApp.voip">>},
{<<"apns-expiration">>, <<"2147483647">>},
{<<"apns-id">>, <<"44e83e09-bfb6-4f67-a281-f437a7450c1a">>}
], <<"{\"aps\":{\"alert\":\"Hello, async user callback\"}}">>
}.
Resp = {ok,[{uuid,<<"44e83e09-bfb6-4f67-a281-f437a7450c1a">>},
{status,<<"200">>},
{status_desc,<<"Success">>}]}.
See also: apns_erlv3_session:async_send_cb/4.
send(Name, Notification) -> Result
Name = fsm_ref()Notification = notification()Result = sync_send_reply()
Equivalent to send(Name, Notification, []).
send(Name, Notification, Opts) -> Result
Name = fsm_ref()Notification = notification()Opts = gen_proplist()Result = sync_send_reply()
Send a notification specified by proplist Notification
to Name with options Opts (currently unused).
Set the notification to expire in a very very long time.
Send an alert with a sound and extra data:
Name = 'com.example.AppId',
Notification = [
{alert, <<"Hello">>},
{token, <<"ea3f...">>},
{aps, [
{sound, <<"bang">>},
{extra, [{a, 1}]}]}
],
sc_push_svc_apnsv3:send(Name, Notification).
start_link(Sessions) -> Result
Sessions = sessions()Result = {ok, pid()} | {error, term()}
Sessions is a list of proplists.
Each proplist is a session definition containing
name, mod, and config keys.
See also: apns_erlv3_session:start_link/1.
start_session(Name, Opts) -> Result
Name = atom()Opts = session()Result = {ok, pid()} | {error, already_started} | {error, term()}
Start named session for specific host and certificate as
supplied in the proplist Opts.
See also: apns_erlv3_session_sup:start_child/2.
stop_session(Name) -> Result
Name = atom()Result = ok | {error, Reason}Reason = any()
Stop named session.