ExOneSignal

A simple interface to interact with OneSignal's push notification API.

Installation

This package can be installed by adding ex_one_signal to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_one_signal, "~> 0.1.0"}
  ]
end

Docs

The docs can be found at https://hexdocs.pm/ex_one_signal.

Usage

Config

Add the following to your project's config.exs

config :ex_one_signal, ExOneSignal,
  api_key: "your-one-signal-api-key",
  app_id: "your-one-signal-app-id"

Simple Notification

To create a notification, all you'll need is to set a message body (contents) and add at least one target user (include_player_ids).

import ExOneSignal.Notification, except: [new: 0]
alias ExOneSignal.Notification

Notification.new
|> set_body("Example Body")
|> add_player("one-signal-player-id")
|> ExOneSignal.deliver

Adding a Title

You can add a title (headings) and the default language will be English.

iex> set_title(Notification.new, "Title")
%Notification{headings: %{en: "Title"}}

Alternatively, you can add titles for multiple languages

iex> Notification.new
iex> |> set_title("English", :en)
iex> |> set_title("Français", :fr)
%Notification{headings: %{en: "English", fr: "Français"}}

Adding a Message Body

You can add a body (contents) and the default language will be English.

iex> set_body(Notification.new, "Body")
%Notification{contents: %{en: "Body"}}

Alternatively, you can add bodies for multiple languages

iex> Notification.new
iex> |> set_body("English", :en)
iex> |> set_body("Français", :fr)
%Notification{contents: %{en: "English", fr: "Français"}}

Specifying Target Users

To deliver a notification to a user's device, all you need is to add their OneSignal player_id_token.

iex> Notification.new
iex> |> add_player("one-signal-player-token")
%Notification{include_player_ids: ["one-signal-player-token"]}

Adding Additional Meta Data

Notifications can contain additional meta information that will be readable by your client application (e.g. iOS or Android applications).

iex> Notification.new
iex> |> add_data(:targetUrl, "https://example.com")
%Notification{data: %{url: "https://example.com"}}

Asynchonous Delivery

If you don't want to lock up your current process waiting on the network request to OneSignal, you can use the deliver_later function to fire off the notification in the background.

iex> Notification.new
iex> |> ExOneSignal.deliver_later
{:ok, #PID<0.255.0>}

To get the response from the async request, just setup a receive request and match on the returned process identifier. It is highly recommended with this approach to use a timeout in the receive block.

{:ok, process_id} = ExOneSignal.deliver_later(Notification.new)

receive do
  {^process_id, response} ->
    case response do
      {:ok, body} ->
        # do something
    end
  after
    1_000 ->
      # the receive timed out after 1 second
end

Alternatively, supply a callback function that will fire when the request finishes.

ExOneSignal.deliver_later(Notification.new, fn(response) ->
  case response do
    {:ok, body} ->
      # do something
  end
end)