Push Notifications

Setup

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

Admin Panel

See Firebase Application Configuration in Chapter 6

Client Setup

See the 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. When you receive a new FCM token in your handler, which might look like this, for example

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 one, or delete an existing one. 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.

Lua Implementation

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

//It's not strictly necessary to wrap this in a pcall,
//but useful to avoid errors in debug environments.
local status, notification = pcall(require, "namazu.elements.notification")

You must then build the notification. Get an instance of a notifcation builder from the imported class

local builder = notification.builder()

and 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. 
     * Note - this happens automatically when getting a new builder
     */
    NotificationBuilder application(Application application);

    /**
     * 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.
     * Note - this will be "default" if unspecified
     */
    NotificationBuilder sound(String sound);

    /**
     * Adds a single key/value property.  
     * Individual keys should be non-empty and all values should be non-null    
     */
    NotificationBuilder add(@Nonnull String key, @Nonnull String value);

    /**
     * Adds all properties in the passed in mapping to the notification 
     * being built.  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.     
     */
    NotificationBuilder addAll(Map<String,String> properties);

    /**
     * Constructs the instance of Notification with all of the configured 
     * information. This returns a new instance of Notification for each 
     * call which can be treated independently.
     */ 
    Notification build();

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