ProMotion-push
ProMotion-push is push notification support, extracted from the popular RubyMotion gem ProMotion and was created by Infinite Red, a web and mobile development company based in Portland, OR and San Francisco, CA. While you're welcome to use it, please note that we rely on the community to maintain it. We are happy to merge pull requests and release new versions but are no longer driving primary development.
Installation
gem 'ProMotion-push'
Usage
AppDelegate
Include PM::DelegateNotifications to add a few methods to PM::Delegate.
# app/app_delegate.rb
class AppDelegate < PM::Delegate
include PM::DelegateNotifications
def on_load(app, options)
register_for_push_notifications :badge, :sound, :alert, :newsstand
PM.logger.info registered_push_notifications
# ...
end
def on_unload
unregister_for_push_notifications
end
def on_push_registration(token, error)
PM.logger.info token.description
end
def on_push_notification(notification, launched)
PM.logger.info notification.to_json
end
end
register_for_push_notifications(*types)
Method you can call to register your app for push notifications. You'll also want to implement
on_push_notification
and on_push_registration
.
def on_load(app, options)
register_for_push_notifications :badge, :sound, :alert, :newsstand # or :all
# ...
end
unregister_for_push_notifications
Unregisters from all push notifications.
def logging_out
unregister_for_push_notifications
end
NOTE: From a screen you'll have to reference the app_delegate:
def log_out
app_delegate.unregister_for_push_notifications
end
on_push_registration(token, error)
Method that is called after you attempt to register for notifications. Either token
or error
will be provided.
def on_push_registration(token, error)
if token
# Push token to your server
else
# Display the error
end
end
on_push_notification(notification, launched)
Method called when the app is launched via a notification or a notification is received
in-app. notification
is a
PM::PushNotification
object which is a thin wrapper around the notification hash provided by iOS. launched
is a boolean letting you know whether the notification initiated your app's launch (true) or
if your app was already running (false).
def on_push_notification(notification, launched)
notification.to_json # => '{"aps":{"alert":"My test notification","badge":3,"sound":"default"}, "custom": "Jamon Holmgren"}'
notification.alert # => "My test notification"
notification.badge # => 3
notification.sound # => "default"
notification.custom # => "Jamon Holmgren"
end
ProMotion-push automatically adds support for handling push notifications while your app is in the background. If your push notification payload includes content-available: 1
then you may have an opportunity to pre-fetch data. The return value of the on_push_notification
method should one of the following that best matches the result: :new_data
, :no_data
, :failed
. The default is :no_data
, so you don't need to return anything if you did not fetch any data. For example:
# Payload:
# {
# "aps": {
# "content-available": 1,
# "alert": "My test notification",
# "badge": 3,
# "sound": "default"
# },
# "type": "new_messages"
# }
def on_push_notification(notification, launched)
if notification.type == "new_messages"
MessagesScreen.load_data
return :new_data
end
end
registered_push_notifications
Returns the currently registered notifications as an array of symbols.
def some_method
registered_push_notifications # => [ :badge, :sound, :alert, :newsstand ]
end
Actionable Notifications
As of IOS 8, notifications can include action buttons in the lock screen, notification banners and notification center. This is called the "Minimal" context and supports 2 actions. The "Default" context supports up to 4 Actions and applies when alerts are opened as popups.
To use these features with ProMotion-push you need to:
Define each action you plan to include in a notification for either context.
approve_action = UIMutableUserNotificationAction.new.tap do | action |
action.identifier = "APPROVE_ACTION"
action.title = "Approve"
action.activationMode = UIUserNotificationActivationModeBackground
action.authenticationRequired = false
end
Register your actions by calling register_push_notification_category
from your AppDelegate code prior to register_for_push_notifications
, for each category of action you intend to use. Note that you must include a separate array for the actions to show in the minimal context.
def on_load(app, options)
register_push_notification_category 'APPROVAL_ACTIONS', [approve_action, deny_action, self_destruct_action], minimal: [approve_action]
register_push_notification_category 'SECOND_CATEGORY_NAME', # ...
# ...
register_for_push_notifications :badge, :sound, :alert, :newsstand # or :all
# ...
end
Include one of the categories you just defined in your push payload
{
"aps" : {
"alert" : "Do you approve?",
"category" : "APPROVAL_ACTIONS"
}
}
Implement on_push_notification_action
in your AppDelegate to handle the selected action
def on_push_notification_action(action, notification)
# handle the action
case action
when 'APPROVE_ACTION'
# approve
when 'DENY_ACTION'
# deny
end
end
ProMotion::PushNotification
You receive this object in your AppDelegate's on_push_notification
method.
def on_push_notification(notification, launched)
notification.to_json # => '{"aps":{"alert":"My test notification","badge":3,"sound":"default"}, "custom": "Jamon Holmgren"}'
notification.alert # => "My test notification"
notification.badge # => 3
notification.sound # => "default"
notification.custom # => "Jamon Holmgren"
end
The best way to test push notifications is on a device, but it's often useful to test them in the simulator. We provide a way to do that from the REPL or in code.
# In REPL
PM::PushNotification.simulate(alert: "My test", badge: 4, sound: "default", custom: "custom", launched: true)
def on_push_notification(notification, launched)
notification.aps # => { alert: "My test", badge: sound: "default"}
notification.alert # => "My test"
notification.custom # => 'custom'
end
alert
Returns the alert string for the push notification object.
notification.alert # => "My test notification"
badge
Returns the badge number for the push notification object, if it exists.
notification.badge # => 3
sound
Returns a string representing the sound for the push notification object, if it exists.
notification.sound # => "sound"
to_json
Returns a json string representation of the push notification object.
notification.to_json # => '{"aps":{"alert":"My test notification","sound":"default"},"custom":"something custom"}'
(custom methods)
A method_missing
implementation will respond to all methods that are keys in the notification hash. It
will raise a NoMethodError if there isn't a corresponding key.
# Given: '{"aps":{"alert":"My test notification","sound":"default"}, "my_custom_key": "My custom data"}'
notification.my_custom_key # => "My custom data"
notification.no_key_here # => NoMethodError
notification
Returns the raw notification object provided by iOS.
notification.notification # => Hash
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Make some specs pass
- Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
Premium Support
ProMotion and ProMotion-push, as open source projects, are free to use and always will be. Infinite Red offers premium ProMotion and ProMotion-push support and general mobile app design/development services. Email us at hello@infinite.red to get in touch with us for more details.