Action Push Native

To support multiple apps (e.g., a 'calendar' app and an 'email' app), define unique keys in config/push.yml under the platform section (apple or google). You can also define a shared configuration for a platform that gets merged into app-specific settings.

In your notification classes, set self.application to match the key used in push.yml.

class CalendarPushNotification < ApplicationPushNotification
  self.application = "calendar"
end

shared:
  apple:
    application:
      team_id: your_apple_team_id
    calendar:
      key_id: <%= ... %>
      topic: calendar.bundle.identifier

To install the gem and set up the necessary database migrations, run the following commands in your terminal:

bundle add action_push_native
bin/rails g action_push_native:install
bin/rails action_push_native:install:migrations
bin/rails db:migrate

The ActionPushNative::Notification class extends ActiveModel::Callbacks and defines delivery callbacks. You can use these to run logic (like logging or modifying the notification) immediately before or after a notification is delivered via deliver_to.

To use them, define your logic within the delivery callback lifecycle in your notification subclass.

class MyNotification < ActionPushNative::Notification
  define_model_callbacks :delivery

  after_delivery do
    Rails.logger.info "Notification delivered!"
  end
end

The library uses a hierarchical configuration lookup via ActionPushNative.config_for(platform, notification):

1. Platform Level: It first looks up the configuration for the specified :platform (e.g., :apple).
2. Application Level: If the notification.application is present, it looks for a key matching that application name within the platform configuration.
3. Merging: It merges the application-specific settings into the base :application configuration block of that platform. This allows you to define common platform settings under an :application key and override them for specific apps.

If the platform is not configured in config/push.yml, an error is raised.

If ApplicationPushDevice does not meet your needs, you can use a custom class. The custom object must:

1. Be serializable/deserializable by ActiveJob.
2. Respond to token and platform methods.
3. Implement a push(notification) method.

class CustomDevice
  def token; @token; end
  def platform; @platform; end

  def push(notification)
    notification.token = token
    ActionPushNative.service_for(platform, notification).push(notification)
  rescue ActionPushNative::TokenError => error
    # Custom token error handling
  end
end

You can deliver notifications to a single device or an array of devices. It is highly recommended to use deliver_later_to for asynchronous delivery to ensure retry logic and error handling are utilized.

• deliver_later_to(device): Asynchronous delivery (recommended).
• deliver_later_to([device1, device2]): Asynchronous delivery to multiple devices.
• deliver_to(device): Synchronous delivery.

device = ApplicationPushDevice.create!(name: "iPhone", token: "token", platform: "apple")

notification = ApplicationPushNotification.new(
  title: "Hello world!",
  body: "Welcome to Action Push Native"
)

# Recommended
notification.deliver_later_to(device)

# Or multiple
notification.deliver_later_to([device1, device2])

# Synchronous
notification.deliver_to(device)

You can define Active Record-style callbacks in your notification class to modify or abort delivery. The callback block receives the notification object. You can access extra context passed during initialization via notification.context.

class CalendarPushNotification < ApplicationPushNotification
  before_delivery do |notification|
    # Abort if the calendar is expired
    throw :abort if Calendar.find(notification.context[:calendar_id]).expired?
  end
end

# Usage with context
data = { calendar_id: 123 }
notification = CalendarPushNotification.with_apple(data).new(calendar_id: 123)
notification.deliver_later_to(device)

Silent notifications can be created using the .silent method. This creates a notification for both Apple and Google that does not trigger a visual alert (no title, body, or badge). You can still attach data using .with_data.

notification = ApplicationPushNotification.silent.with_data(id: 1).new

Action Push Native loads its configuration from a YAML file located at config/push.yml within your Rails application.

Configuration is organized by platform (e.g., :apple, :google). You can also provide application-specific overrides. If a notification has an application attribute, the configuration for that specific application will be merged into the platform's base configuration, with the application-specific settings taking precedence.

# Example config/push.yml structure
apple:
  application:
    key_id: "YOUR_KEY_ID"
    team_id: "YOUR_TEAM_ID"
  my_app_name:
    key_id: "OVERRIDE_KEY_ID"

google:
  server_key: "YOUR_FCM_SERVER_KEY"