Mobile Push: instructions for developers

This documentation is a comprehensive guide for configuring and managing mobile push-related events in the Meiro system. It covers prerequisites, API endpoints, request structures, and the management of registration tokens.

1. Public API interface

This section outlines the public endpoints and their corresponding request structures for handling mobile push-related events within the system. 

1.1.  FCM Registration Token Registered

The endpoint allows clients to submit Firebase Cloud Messaging (FCM) registration tokens for mobile devices, initializing the profile's mobile push system attribute. Without sending this event, reaching out to the user's device via Mobile Push is impossible.

Remember, this event should be sent once the user gives consent to receive mobile push notifications. Additionally, Firebase SDK has to be integrated and running to include the registration token in the event.

ME API Endpoint:
POST /meiro_mobile

Request Example:

{
  user_id: "f653a690-21b4-4d3e-865f-bd4568153ba7", // required string, UUID generated uniquely for each user of the application 
  event_type: "fcm_registration_token_registered", //required string
  event_timestamp: "2024-02-20T13:00:00.000Z", //required string
  version: "1.0.0", //required string, version of the event structure
  session_id: "MTIzNDU2Nzg5MDUyNTAwMDpmdWxsZXJfYmFy", // optional string, base64 session id (timestamp&user_id)
  event_data: { // optional object 
     	[key]: "any value" // optional for passing additional custom data
},
  app: { // required object
    id: "1:353411649331:android:7ae86e76054a2720fa7695", // required string, ID of the Firebase project's application
    name: "Your app name", // required string
    version: "1.2.0", // required string, application version
    language: "en" // optional string, 2 characters ISO-639-1 (needed when you want to target users by language)
  },
  os: { // required object
    type: "android", // required string, "android" or "ios"
    version: "10" // optional string
  },
  device: { // optional object
    manufacturer: "Samsung", // optional string
    model: "Galaxy Note 7" // optional string
  },
  firebase: { // required object
    project_id: "meiro-project", // required string
    registration_token: "cn5G7wfiS3eWZijQtjBNWT:APA91bHGzrQ2njYAA73lYV3gbgC9MT7RR4guLtS1tSVDPSTKCR5USuUKkwuCyx4jVaErBQP7WwUrYiHXnqVk3QcF95Y1a9VNXWpuZG7ZdVZWxxqppEquRlTDSfm3d7hC6eDRMDAB9Jgg" // required string, FCM registration token
  }
}

You can pass additional identifiers within the event_data object, such as Adjust ID, Appsflyer ID, Google Playstore AdID, and IDFA. Including them allows to correctly stitch mobile push events with the corresponding events.

Response Example:

200 - This response indicates that the FCM Registration Token provided in the request has been successfully received. 

The error that may occur:

400 - Bad Request: Invalid Request  (e.g., missing required properties in the request or other validation errors)

{
  message: "validation: registration_token is required property",
  status: "error"
}

---

1.2. FCM Registration Token Refreshed

Automatically refreshes a previously registered token by periodically sending the FCM Registration Token Refreshed event once a month, regardless of the application's running state or launching status. This process is facilitated by sending the event using background processes via WorkManager (Android) or BackgroundTasks framework (iOS) to ensure the token remains active. The request payload must include the FCM refresh timestamp.

ME API Endpoint:
POST /meiro_mobile

Request Example:

{
  user_id: "f653a690-21b4-4d3e-865f-bd4568153ba7", // required string, UUID generated uniquely for each user of the application
  event_type: "fcm_registration_token_refreshed", //required string
  event_timestamp: "2024-02-20T14:00:00.000Z", //required string
  version: "1.0.0", //required string, version of the event structure
  event_data: { // required object
    fcm_registration_token_refresh_timestamp: "2024-02-20T14:00:00.000Z" //required,
  },
  app: { // required object
    id: "1:353411649331:android:7ae86e76054a2720fa7695", // required string, ID of the Firebase project's application
    name: "Your app name",// required string
    version: "1.2.0", // required string, application version
    language: "en" // optional string, 2 characters ISO-639-1 (needed when you want to target users by language)
  },
  os: { // required object
    type: "android",// required string, "android" or "ios"
    version: "10" // optional string
  },
  device: { // optional object
    manufacturer: "Samsung", // optional string
    model: "Galaxy Note 7" // optional string
  },
  firebase: { // required object
    project_id: "meiro-project", // required string
    registration_token:
"cn5G7wfiS3eWZijQtjBNWT:APA91bHGzrQ2njYAA73lYV3gbgC9MT7RR4guLtS1tSVDPSTKCR5USuUKkwuCyx4jVaErBQP7WwUrYiHXnqVk3QcF95Y1a9VNXWpuZG7ZdVZWxxqppEquRlTDSfm3d7hC6eDRMDAB9Jgg" // required string, FCM registration token
  }
}

Response Example:
200 - indicates that the FCM Registration Token Refresh event has been successfully received.

The error that may occur:

400 - Bad Request: Invalid Request  (e.g., missing required properties in the request or other validation errors)

{
  message: "validation: registration_token is required property",
  status: "error"
}

---

Key points

• user_id is a unique identifier for each device and app installation, similar to the meiro_user_id used on the website. It's essential to generate a unique UUID identifier and store it persistently within the app's storage. The user_id should be included in every event sent to the Mobile Push channel. In case user_id is removed from the app storage, it should be regenerated.

• You can also specify the session_id, which identifies user sessions within the app. Its ID changes once the user is inactive for more than 30 minutes.

• Remember to include the app version in the app.version object, enabling segmentation of users based on this criterion. Additionally, for multilingual apps, add the language to the app.language object to facilitate targeting specific users with particular languages.

---

2.  Custom data payload

In addition to standard push notification content, you have the option to send a custom data payload together with the mobile push content, giving you more flexibility and customization options. For example, you may want to specify:

• a unique URI with the attribute placeholder in the value
• some required category within a list of values
• a current timestamp once it’s created or sent

To implement the custom data payload, configure a schema on the MP channel settings, which defines the structure of the custom data payload. The schema is configured using JSON format and should include definitions for each custom data field, specifying its title, default value (if applicable), enum, and type.

The custom data payload is rendered as a form that is dynamically adjusted based on the schema configuration, allowing for effective visualization and customization of the payload.

After configuring the custom data payload, it is stored and sent together with the current data object for mobile push campaigns.

Remember: You can personalize fields using the LiquidJS template language. For instance, apply this language inside the default value to dynamically prepopulate the known values for each profile. 

Example of custom data schema

To provide a comprehensive illustration of implementing a custom data payload schema, let's delve into an example with various data types and configurations:

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "title": "Category",
      "default": "ESSENTIAL",
      "enum": ["ESSENTIAL", "BOOKING_INSPIRATIONAL", "INSPIRATIONAL"]
    },
    "createdAt": {
      "type": "string",
      "title": "Created At",
      "format": "date-time"
    },
    "requireUserConfirmation": {
      "type": "boolean",
      "title": "Require user confirmation",
      "default": true
    },
    "bookingUri": {
      "type": "string",
      "title": "Booking",
      "description": "Booking ID"
    }
  },
  "required": ["category", "requireUserConfirmation", "bookingUri"]
}

In this example:

• Category is defined as a string representing the notification category. Enumerated values such as "ESSENTIAL," "BOOKING_INSPIRATIONAL," and "INSPIRATIONAL" are allowed. If no value is provided, the default is set to "ESSENTIAL."

• CreatedAt is a datetime string that serves to order notifications in the in-app notification center.

• Require User Confirmation is a boolean flag that determines whether user confirmation is necessary for displaying the notification within the application. By default, it's set to true.

• Booking URI is a string specifying where we’ll have to use bookingId from the attribute value.

Remember: When creating a custom data schema, avoid using any reserved words, including action, url, from, notification, message_id, message_type, or any word starting with google or gcm in custom key-value pairs.

---

3. Structure of FCM Messages

This section provides an overview of the structure of Firebase Cloud Messaging (FCM) messages that are sent within the Meiro system. Understanding this structure is crucial for app developers to incorporate the received data effectively into their applications.

Message Structure

The FCM messages sent from the Meiro system consist of several key components, each serving a specific purpose:

• Token: The unique token identifying the recipient device to which the notification will be delivered.
• Notification Body:
  • Title: The title of the notification displayed to the user.
  • Body: The main content or message of the notification.
  • Image URL: An optional URL pointing to an image associated with the notification, enhancing visual appeal. It can be empty, in case it's not set, or it contains an attribute placeholder for which the value is missing
• Settings:
  • Android Settings:
    • TTL (Time to Live): Specifies the time-to-live for the notification on Android devices, ensuring timely delivery and expiration.
  • APNS (Apple Push Notification Service) Settings:
    • Headers: Custom headers for APNS, such as the expiration time of the notification.
  • Web Push Settings:
    • Headers: Custom headers for web push notifications.
• Data Payload:
  • Action: Indicates the action to be performed upon interaction with the notification, such as opening an app, browser, or a deep link. 
  • URL: The deep link or URL associated with the action, directing users to a specific location or functionality within the app. If the action is "app", the URL key will be present but empty.
  • Message ID: A unique identifier for tracking and managing the notification message.
  • Additional Custom Payload: Any additional custom data or payload relevant to the notification, facilitating further customization and functionality within the app.

Learn more: you can refer to the Firebase documentation for more details.

Example of FCM message structure

{
  "message": {
    "token": "your_device_token_here",
    "notification": {
      "title": "title_of_mobile_push",
      "body": "body_of_mobile_push",
"image_url": "https://client.me.meiro.dev/sdk/images/example.jpeg"
},
    "android": {
        "ttl": "42s"
    },
    "apns": {
        "headers": {
            "apns-expiration": "42"
        }
    },
    "webpush": {
        "headers": {
            "TTL": "42"
        }
    },
    "data": {
        "action": "deeplink",
        "url": "https://example.com/launch?event=one",
        "message_id": "593ebbb4-8a1c-4a1e-b10d-16cdf2413cdb",
        "aditional": "custom_payload_here"
    }
  }
}

---

4. Implementing Deep Links in Mobile Apps

Deep linking lets you send users directly to specific pages or content within your mobile app, enhancing the user experience and increasing engagement. 

Here are key issues you need to consider in implementation:

1. To implement deep links, you need to set them up in the mobile app. Register the app's deep links to target specific screens or content within your app that you wish to make accessible through deep linking. For further details, refer to the provided article.
2. Once you've added the deep link to the mobile push data and your users interact with the push notification, the app will automatically redirect them to the registered deep link and open the specified screen.

Remember: after configuring the deep links, test them to ensure they are working as expected.