Push Notifications

Push Notifications can be configured in Elements using Firebase, so your apps and games can have fully featured notifications for any aspect of engagement.

Setup

Elements uses Firebase for Push Notifications. There are three places that will need configuration for Push Notifications, namely:

Admin Panel

See Firebase Application Configuration.

Client Setup

See Google's Firebase documentation for more information on how to set up Firebase for your client platform.

Once you have the Firebase plugin set up in your client project and have added the messaging handlers, use the Elements generated FirebaseCloudNotificationsApi to associate the Firebase Cloud Messaging (FCM) token with your profile.

You'll receive a new FCM token in your handler, which should look something like this:

C#
void OnTokenReceived(object sender, Firebase.Messaging.TokenReceivedEventArgs token)

Simply create a new FCMRegistration object and assign the Token property of the TokenReceivedEventArgs to the RegistrationToken property.

You can now use the FirebaseCloudNotificationsApi methods to create a new FCM registration, updating an existing registration, or delete an existing registration.

A Profile must have an FCM token associated with it before it can receive Push Notifications, so it's generally best to do this as part of the sign up or login flow.

Only one registration can be active for a Profile at a time, so logging into a second device and updating the token will stop push notifications from reaching the first device.

Lua Implementation

To send a push notification from your Lua code, you must first import the corresponding Elements class:

local status, notification = pcall(require, "namazu.elements.notification")

It's not strictly necessary to wrap this in a pcall, but useful to avoid errors in debug environments.

You must then build the notification by getting an instance of a notification builder from the imported class:

local builder = notification.builder()

Then, you can assign various properties using the builder pattern, for example:

   builder:title(title)
          :message(message)
          :sender(sender)
          :recipient(recipient)
          :build()
          :send()

A notification builder adheres to the following interface.

Assign the Profile of the sender:

NotificationBuilder sender(Profile sourceProfile);

Assign the application:

NotificationBuilder application(Application application);

This happens automatically when getting a new builder.

Assign the Profile that will receive the notification:

NotificationBuilder recipient(Profile recipient);

The title text of the notification:

NotificationBuilder title(String title);

The message/body text of the notification:

NotificationBuilder message(String message);

Specifies the sound to play when delivering the message.

NotificationBuilder sound(String sound);

This will be "default" if unspecified.

Adds a single key/value property:

NotificationBuilder add(@Nonnull String key, @Nonnull String value);

Individual keys should be non-empty and all values should be non-null.

Add all properties in the passed in mapping to the notification being built:

NotificationBuilder addAll(Map<String,String> properties);

Any keys which are null or empty Strings will be ignored. Any values which are null will be ignored. For all other entries, if any keys previously exist in the notification, they will be replaced by the value specified in the passed in Map.

Construct the instance of Notification with all of the configured information:

Notification build();

This returns a new instance of Notification for each call which can be treated independently.

Once built, simply call :send() and you're all set!

Sending a notification will throw an exception if the Firebase Configuration in the ApplicationConfiguration of the Application it has been assigned is either missing or invalid!