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.

Public API interface

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

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", // UUID string, required 
  event_type: "fcm_registration_token_registered", //required
  event_timestamp: "2024-02-20T13:00:00.000Z", //required
  version: "1.0.0", //required
  session_id: "MTIzNDU2Nzg5MDUyNTAwMDpmdWxsZXJfYmFy", // optional, 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, it comes from the mobilesdk_app_id section in the app's google-services.json file
    name: "Firebase Cloud Messaging",// required string
    version: "1.0.0", // required string
    language: "en" // optional, 2 characters ISO-639-1 (needed when you want to target users by language)
  },
  os: { // required object
    type: "android", // required enum('android', '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
  }
}

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"
}

---

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", // UUID string, required 
  event_type: "fcm_registration_token_refreshed", //required
  event_timestamp: "2024-02-20T14:00:00.000Z", //required
  version: "1.0.0", //required
  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, it comes from the mobilesdk_app_id section in the app's google-services.json file
    name: "Firebase Cloud Messaging",// required string
    version: "1.0.0", // required string
    language: "en" // optional, 2 characters ISO-639-1 (needed when you want to target users by language)
  },
  os: { // required object
    type: "android", // required enum('android', '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
  }
}

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.