Class: Expo::Push::Notification

Inherits:
Object
  • Object
show all
Defined in:
lib/push/notification.rb

Overview

Data model for PushNotification.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(_recipient = []) ⇒ Notification

Returns a new instance of Notification.



15
16
17
18
 
# File 'lib/push/notification.rb', line 15

def initialize(_recipient = [])
  self.recipients = []
  self._params = {}
end

Instance Attribute Details

#recipients ⇒ Object

rubocop:disable Metrics/ClassLength



9
10
11
 
# File 'lib/push/notification.rb', line 9

def recipients
  @recipients
end

Class Method Details

.to(recipient) ⇒ Object 



11
12
13
 
# File 'lib/push/notification.rb', line 11

def self.to(recipient)
  new.to(recipient)
end

Instance Method Details

#<<(recipient) ⇒ Object Also known as: add_recipient

Add a single recipient

Must be a valid Expo Push Token, or a PushTokenInvalid error is raised.

Raises:

See Also:



307
308
309
310
311
312
313
 
# File 'lib/push/notification.rb', line 307

def <<(recipient)
  raise PushTokenInvalid.new(token: recipient) unless Expo::Push.expo_push_token?(recipient)

  recipients << recipient

  self
end

#as_json ⇒ Object 



332
333
334
 
# File 'lib/push/notification.rb', line 332

def as_json
  { to: recipients }.merge(_params.compact)
end

#badge(value) ⇒ Object

Note:

iOS only

Set or overwrite the new badge count.

Use 0 to clear, use nil to keep as is.



230
231
232
233
234
235
 
# File 'lib/push/notification.rb', line 230

def badge(value)
  _params[:badge] = value.nil? ? nil : value.to_i
  self
rescue NoMethodError
  raise ArgumentError, 'badge must be numeric or nil'
end

#body(value) ⇒ Object Also known as: content

Set or overwrite the body (content).

The message to display in the notification.



93
94
95
96
97
98
 
# File 'lib/push/notification.rb', line 93

def body(value)
  _params[:body] = value.nil? ? nil : String(value)
  self
rescue NoMethodError
  raise ArgumentError, 'body must be nil or string-like'
end

#category_id(value) ⇒ Object

Set or overwrite the category ID

ID of the notification category that this notification is associated with. Must be on at least SDK 41 or bare workflow.

Notification categories allow you to create interactive push notifications, so that a user can respond directly to the incoming notification either via buttons or a text response. A category defines the set of actions a user can take, and then those actions are applied to a notification by specifying the categoryId here.

See Also:



275
276
277
278
279
280
 
# File 'lib/push/notification.rb', line 275

def category_id(value)
  _params[:categoryId] = value.nil? ? nil : String(value)
  self
rescue NoMethodError
  raise ArgumentError, 'categoryId must be string-like or nil'
end

#channel_id(value) ⇒ Object Also known as: channel_identifier

Note:

If left nil, a “Default” channel will be used, and Expo will create the channel on the device if it does not yet exist. However, use caution, as the “Default” channel is user-facing and you may not be able to fully delete it.

Note:

Android only

Set or overwrite the channel ID.

ID of the Notification Channel through which to display this notification. If an ID is specified but the corresponding channel does not exist on the device (i.e. has not yet been created by your app), the notification will not be displayed to the user.



252
253
254
255
256
257
 
# File 'lib/push/notification.rb', line 252

def channel_id(value)
  _params[:channelId] = value.nil? ? nil : String(value)
  self
rescue NoMethodError
  raise ArgumentError, 'channelId must be string-like or nil to use "Default"'
end

#count ⇒ Object 



328
329
330
 
# File 'lib/push/notification.rb', line 328

def count
  recipients.length
end

#data(value) ⇒ Object

Set or overwrite the data.

Data must be a Hash, or at least be JSON serializable as hash.

A JSON object delivered to your app. It may be up to about 4KiB; the total notification payload sent to Apple and Google must be at most 4KiB or else you will get a “Message Too Big” error.



48
49
50
51
52
53
54
55
56
57
 
# File 'lib/push/notification.rb', line 48

def data(value)
  json_data = value.respond_to?(:as_json) ? value.as_json : value.to_h

  raise ArgumentError, 'data must be hash-like or nil' if !json_data.nil? && !json_data.is_a?(Hash)

  _params[:data] = json_data
  self
rescue NoMethodError
  raise ArgumentError, 'data must be hash-like, respond to as_json, or nil'
end

#expiration(value) ⇒ Object

Set or overwrite the time to live based on a unix timestamp.

Timestamp since the UNIX epoch specifying when the message expires. Same effect as ttl (ttl takes precedence over expiration).

See Also:



174
175
176
177
178
179
 
# File 'lib/push/notification.rb', line 174

def expiration(value)
  _params[:expiration] = value.nil? ? nil : value.to_i
  self
rescue NoMethodError
  raise ArgumentError, 'ttl must be numeric or nil'
end

#mutable_content(value) ⇒ Object Also known as: mutable

Set or overwrite the mutability flag.

Use nil to use the defaults.

Specifies whether this notification can be intercepted by the client app. In Expo Go, this defaults to true, and if you change that to false, you may experience issues. In standalone and bare apps, this defaults to false.



292
293
294
295
 
# File 'lib/push/notification.rb', line 292

def mutable_content(value)
  _params[:mutableContent] = value.nil? ? nil : !value.nil?
  self
end

#prepare(targets) ⇒ Object

Allows overwriting the recipients list which is necessary to prepare the notification when chunking.



322
323
324
325
326
 
# File 'lib/push/notification.rb', line 322

def prepare(targets)
  dup.tap do |prepared|
    prepared.reset_recipients(targets)
  end
end

#priority(value) ⇒ Object

Note:

On Android, normal-priority messages won’t open network connections on sleeping devices and their delivery may be delayed to conserve the battery. High-priority messages are delivered immediately if possible and may wake sleeping devices to open network connections, consuming energy.

Note:

On iOS, normal-priority messages are sent at a time that takes into account power considerations for the device, and may be grouped and delivered in bursts. They are throttled and may not be delivered by Apple. High-priority messages are sent immediately. Normal priority corresponds to APNs priority level 5 and high priority to 10.

Set or overwrite the priority.

The delivery priority of the message. Specify “default” or nil to use the default priority on each platform:

  • “normal” on Android

  • “high” on iOS

rubocop:disable Metrics/MethodLength



204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/push/notification.rb', line 204

def priority(value)
  if value.nil?
    _params[:priority] = nil
    return self
  end

  priority_string = String(value)

  unless %w[default normal high].include?(priority_string)
    raise ArgumentError, 'priority must be default, normal, or high'
  end

  _params[:priority] = priority_string
  self
rescue NoMethodError
  raise ArgumentError, 'priority must be default, normal, or high'
end

#reset_recipients(targets) ⇒ Object 



336
337
338
339
 
# File 'lib/push/notification.rb', line 336

def reset_recipients(targets)
  self.recipients = []
  add_recipients(targets)
end

#sound(value) ⇒ Object

Note:

iOS only

Set or overwrite the sound.

Play a sound when the recipient receives this notification. Specify “default” to play the device’s default notification sound, or nil to play no sound. Custom sounds are not supported.

rubocop:disable Metrics/MethodLength, Metrics/AbcSize



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/push/notification.rb', line 112

def sound(value)
  if value.nil?
    _params[:sound] = nil
    return self
  end

  unless value.respond_to?(:to_h)
    _params[:sound] = String(value)
    return self
  end

  json_value = value.to_h

  next_value = {
    critical: !json_value.fetch(:critical, nil).nil?,
    name: json_value.fetch(:name, nil),
    volume: json_value.fetch(:volume, nil)
  }

  next_value[:name] = String(next_value[:name]) unless next_value[:name].nil?
  next_value[:volume] = next_value[:volume].to_i unless next_value[:volume].nil?

  _params[:sound] = next_value.compact

  self
end

#subtitle(value) ⇒ Object Also known as: sub_title

Note:

iOS only

Set or overwrite the subtitle.

The subtitle to display in the notification below the title.



79
80
81
82
83
84
 
# File 'lib/push/notification.rb', line 79

def subtitle(value)
  _params[:subtitle] = value.nil? ? nil : String(value)
  self
rescue NoMethodError
  raise ArgumentError, 'subtitle must be nil or string-like'
end

#title(value) ⇒ Object

Set or overwrite the title.

The title to display in the notification. Often displayed above the notification body.



65
66
67
68
69
70
 
# File 'lib/push/notification.rb', line 65

def title(value)
  _params[:title] = value.nil? ? nil : String(value)
  self
rescue NoMethodError
  raise ArgumentError, 'title must be nil or string-like'
end

#to(recipient_or_multiple) ⇒ Object Also known as: add_recipients

Set or add recipient or recipients.

Must be a valid Expo Push Token, or array-like / enumerator that yield valid Expo Push Tokens, or an PushTokenInvalid error is raised.

See Also:



29
30
31
32
33
34
35
36
37
 
# File 'lib/push/notification.rb', line 29

def to(recipient_or_multiple)
  Array(recipient_or_multiple).each do |recipient|
    self << recipient
  end

  self
rescue NoMethodError
  raise ArgumentError, 'to must be a single Expo Push Token, or an array-like/enumerator of Expo Push Tokens'
end

#ttl(value) ⇒ Object

Note:

On Android, we make a best effort to deliver messages with zero TTL immediately and do not throttle them. However, setting TTL to a low value (e.g. zero) can prevent normal-priority notifications from ever reaching Android devices that are in doze mode. In order to guarantee that a notification will be delivered, TTL must be long enough for the device to wake from doze mode.

Set or overwrite the time to live in seconds.

The number of seconds for which the message may be kept around for redelivery if it hasn’t been delivered yet. Defaults to nil in order to use the respective defaults of each provider:

  • 0 for iOS/APNs

  • 2419200 (4 weeks) for Android/FCM

See Also:



159
160
161
162
163
164
 
# File 'lib/push/notification.rb', line 159

def ttl(value)
  _params[:ttl] = value.nil? ? nil : value.to_i
  self
rescue NoMethodError
  raise ArgumentError, 'ttl must be numeric or nil'
end