Skip to content

Latest commit

 

History

History
192 lines (148 loc) · 7.57 KB

README.md

File metadata and controls

192 lines (148 loc) · 7.57 KB
Raw

Pushkin

Gem Version

Pushkin sends push notifications to Android, iOS and Web clients through the unified simple interface using FCM. You can also show Web Push Notifications using Pushkin implementation.

Usage

How to create notifications

notification = Pushkin.simple_notification_to_users({
  notification_type: "poem",
  users: User.all,
  title: "Ruslan and Ludmila",
  body: "The story of the abduction of Ludmila, the daughter of Prince Vladimir of Kiev, by an evil wizard and the attempt by the brave knight Ruslan to find and rescue her"
})

It creates a push notification with static content to the specified users. Actual user tokens will be queried from the database at the time of sending.

Run this code to send notification immediately using ActiveJob:

notification.send_now

You can also send notifications synchronously:

notification.send_now(async: false)

Creation parameters

Parameter Usage Description
:notification_type Required, String Custom string to distinguish notifications from each other
:users Required, Array/Relation List of users to send push notifications
:title Required, String Notification title
:body Optional, String Notification text
:click_action Optional, Hash Click actions of each platform
:icon Optional, Hash Notification icon for web and android platforms
:is_data_message Optional, Hash Specifies if you want to send data message instead of notification
:data Optional, Hash Any notification data that will be sent in the notification

In any case, :data hash will include following parameters:

Parameter Usage description
:notification_type Required, String Value of :notification_type parameter
:notification_id Required, Integer Unique identifier of created notification

:click_action hash keys

Parameter Usage description
:web Optional, String URL to open in the browser
:ios Optional, String Category in the APNs payload
:android Optional, String Intent filter to launch the Activity

:icon hash keys

key value type description
:web Optional, String Public absolute URL of icon
:android Optional, String Drawable resource name

:is_data_message hash keys

key value type description
:web Optional, Boolean True, if you want to send data message to web client
:ios Optional, Boolean True, if you want to send data message to ios client
:android Optional, Boolean True, if you want to send data message to android client

In case of data messages all notification attributes like title and body will be sent in data instead of notification.

Gem Installation

Add this line to your application's Gemfile:

gem 'pushkin-library'

And then execute:

$ bundle install

Execute in command line:

$ bin/rails generate pushkin:setup

It will generate:

  • migration CreatePushkinTables to create tables for notifications sending.
  • controller Pushkin::Api::V1::TokensController for managing device tokens.
  • routes for tokens controller.

And then run migration:

$ rake db:migrate

By default Pushkin uses FCM_SERVER_KEY environment variable for sending push notifications, but you can configure Pushkin yourself in config/application.rb:

Pushkin.configure do |config|
  config.fcm_server_key = ENV["FCM_SERVER_KEY"]
end

If you want to attach device tokens to users, you need to implement authentication logic in Pushkin::Api::V1::TokensController and add this line to User model:

include Pushkin::Concerns::PushkinUser

Web Push Notifications Setup

Add JavaScript FCM Client App to your Rails App (instructions) without permission request, token access and notifications showing. You just need to create FCM project in FCM console, link FCM libraries and put manifest file to public directory.

Add this lines to your layout file:

<script src="https://www.gstatic.com/firebasejs/5.4.1/firebase-app.js"></script>
<script src="https://www.gstatic.com/firebasejs/5.4.1/firebase-messaging.js"></script>
<link rel="manifest" href="/manifest.json">
<%= javascript_include_tag "pushkin/application" %>

Init FCM messaging object in javascript code and save it to Pushkin:

firebase.initializeApp(yourFirebaseSettings);
var messaging = firebase.messaging();
messaging.usePublicVapidKey(YOUR_PUBLIC_VAPID_KEY);
PUSHKIN.messaging = messaging;

Implement token sending:

Pushkin.prototype.sendFirebaseTokenToServer = function (currentToken) {
  // Send currentToken to server using Pushkin API
}

Init notifications showing, access to token and permission request:

PUSHKIN.initNotifications();
PUSHKIN.requestPermission();

Attention! If you want to show push notifications while browser is closed, you still needs to implement this logic in firebase-messaging-sw.js yourself.

Tokens management API

Request type: POST

Content type: 'application/json'

Request body:

{
  "push_token_info":{
    "platform":"android",
    "token":"123456",
    "old_token":"12345"
  }
}
key value type description
platform Required, String Platform type. Available values: "web", "android", "ios"
token Required, String The token for push notifications sending
old_token Optional, String The old token value to deactivate if token refreshed

If you send the authentication data in this request, Pushkin will attach current user to token. Otherwise, Pushkin will destroy the user-token relation.

Response body:

{
  "success":true,
  "info":"Done"
}
key value type description
success Required, Boolean True, if the request completed without any error
info Required, String Short description of response / Error info

License

The gem is available as open source under the terms of the MIT License.