gcm_erl.md

Module gcm_erl

• Description
• Function Index
• Function Details

Google Cloud Messaging (GCM) API.

Copyright (c) 2015 Silent Circle

Authors: Edwin Fine (efine@silentcircle.com).

Description

This is the API to the GCM Service Provider.

Synopsis

In the example below, all optional values are shown with their defaults if omitted.

Starting a session

   Opts = [
               %% Required GCM API key
               {api_key, <<"ahsgdfjkjkjfdk">>},
               %% Required, even if empty list. Defaults shown.
               {ssl_opts, [
                   {verify, verify_peer},
                   {reuse_sessions, true}
               ]},
               %% Optional, defaults as shown.
               {uri, "https://gcm-http.googleapis.com/gcm/send"},
               %% Optional, omitted if missing.
               {restricted_package_name, <<"my-android-pkg">>},
               %% Maximum times to try to send and then give up.
               {max_attempts, 10},
               %% Starting point in seconds for exponential backoff.
               %% Optional.
               {retry_interval, 1},
               %% Maximum seconds for a request to live in a retrying state.
               {max_req_ttl, 3600},
               %% Reserved for future use
               {failure_action, fun(_)}
           ],
   {ok, Pid} = gcm_erl:start_session('gcm-com.example.MyApp', Opts).

Sending an alert via the API

   RegId = <<"e7b300...a67b">>, % From earlier Android registration
   Opts = [
       {id, RegId},
       {collapse_key, <<"New Mail">>},
       {data, [{msg, <<"You have new mail">>}]}
   ],
   {ok, Result} = gcm_erl:send('gcm-com.example.MyApp', Opts),
   {UUID, Props} = Result.

Sending an alert via a session (for testing only)

   {ok, Result} = gcm_erl_session:send('gcm-com.example.MyApp',
                                                  Opts),
   {UUID, Props} = Result.

Stopping a session

   ok = gcm_erl:stop_session('gcm-com.example.MyApp').

Function Index

async_send/2	Asynchronously send a notification specified by proplist Notification to SvrRef.
async_send/3	Asynchronously send a notification specified by proplist Notification to SvrRef with options Opts.
send/2	Send a notification specified by proplist Notification to SvrRef.
send/3	Send a notification specified by proplist Notification to SvrRef with options Opts.
start_session/2	Start a named session.
stop_session/1	Stop named session.

Function Details

async_send/2

async_send(SvrRef, Notification) -> Result

• SvrRef = term()
• Notification = gcm_json:notification()
• Result = {ok, {submitted, Reply}} | {error, Reason}
• Reply = term()
• Reason = term()

Asynchronously send a notification specified by proplist Notification to SvrRef.

See also: async_send/3, gcm_erl_session:async_send/2.

async_send/3

async_send(SvrRef, Notification, Opts) -> Result

• SvrRef = term()
• Notification = gcm_json:notification()
• Opts = proplists:proplist()
• Result = {ok, {submitted, Reply}} | {error, Reason}
• Reply = term()
• Reason = term()

Asynchronously send a notification specified by proplist Notification to SvrRef with options Opts.

See also: send/3, gcm_erl_session:async_send/3.

send/2

send(SvrRef, Notification) -> Result

• SvrRef = term()
• Notification = gcm_json:notification()
• Result = {ok, Reply} | {error, Reason}
• Reply = term()
• Reason = term()

Send a notification specified by proplist Notification to SvrRef.

See also: send/3, gcm_erl_session:send/2.

send/3

send(SvrRef, Notification, Opts) -> Result

• SvrRef = term()
• Notification = gcm_json:notification()
• Opts = proplists:proplist()
• Result = {ok, Reply} | {error, Reason}
• Reply = term()
• Reason = term()

Send a notification specified by proplist Notification to SvrRef with options Opts. Opts currently only supports {http_headers, [{string(), string()}]} to provide extra headers.

Note that SvrRef may be the registered name or {Name, Node}, where Node is an Erlang node on which the registered process called Name is running.

Example

  Name = 'gcm-com.example.MyApp', % Note: atom() !
  Notification = [
     %% Required, all others optional
     {id, <<"abc">>},
     {collapse_key, <<"Something">>},
     {priority, <<"high">>},
     {content_available, true},
     {data, []},
     {delay_while_idle, false},
     {time_to_live, 3600},
     {restricted_package_name, <<"foo_pkg>>},
     {dry_run, false}
  ],
  gcm_erl:send(Name, Notification, []),
  gcm_erl:send({Name, node()}, Notification, []).

See also: gcm_erl_session:send/3.

start_session/2

start_session(Name::atom(), Opts::gcm_erl_session:start_opts()) -> {ok, pid()} | {error, already_started} | {error, Reason::term()}

Start a named session.

See also: gcm_erl_session:start_link/2.

stop_session/1

stop_session(Name::atom()) -> ok | {error, Reason::term()}

Stop named session.