SDK API v2

Get id for new app instance

Request:

curl --header "content-type: application/json" \
     --request POST \
     --url "https://core.push.express/api/r/v2/apps/:app_id/instances" \
     --data '
{
    "ic_token": "212604ab-4b19-4d24-b8ec-3b8bac401a6a",
    "ext_id": ""
}
'

Body params:

• ic_token, required. Globally unique, local-generated app instance installation token, as described in section 1.1.

• ext_id, optional. External id (for login/logout functionality).

Response:

• 200: New app instance created

  {
    "id": "737112",
    "just_created": true
  }

  • id, string. Created app instance id (use as :ic_id in update info requests)

  • just_created, bool. Logged in to existing instance (via ext_id) or created new device.

Update app instance info

Request:

curl --header "content-type: application/json" \
     --request PUT \
     --url "https://core.push.express/api/r/v2/apps/:app_id/instances/:ic_id/info" \
     --data '
{
    "transport_type": "fcm",
    "transport_token": "dmC6c1abSiaSszJTAGhDpr:APA91bG..._TelL7kq8H0FN-NfKGSd",
    "platform_type": "android",
    "platform_name": "android_api_33",
    "ext_id": "<external_user_id|ic_token>",
    "lang": "en",
    "country": "BR",
    "tz_sec": -3600,
    "tags": { "offer": "google_ads_12321" }
}
'

Body params:

• transport_type, required. Push transport type. One of fcm, onesignal, huawei, apns

• transport_token, optional. transport_type specific token for receiving push

• platform_type, required. Notification rendering platform. One of android, ios, browser

• platform_name, optional. Readable platform name and version, like, android_api_33 or chrome_118

• country, recommended. Sim card, locale or some other platform-based country code.

  Accepts ISO3166-1, alpha-2 country code.

  MUST NOT be determined by current network IP, better send nothing!

  Example (don't forget to check exceptions and return empty string on any):

  val tm = context.getSystemService(Context.TELEPHONY_SERVICE) as TelephonyManager
  return tm.simCountryIso.takeIf { it.isNotEmpty() } ?: tm.networkCountryIso.takeIf { it.isNotEmpty() }

• lang, highly recommended. Platform-based language. Accepts BCP 47 language tag

  Example: Locale.getDefault().language

• tz_sec, recommended. Platform timezone east-shift from UTC-0, in seconds, like 3600, or -7200. Example: TimeZone.getDefault().rawOffset / 1000

• tags, optional. User-specified string tags, map of strings with string keys. Predefined tag names: ad_id, offer, webmaster

• onscreen_count, optional. How many times app was opened and showed on screen (how many times the app was used)

• onscreen_sec, optional. How many seconds app was on screen (how much time the app was used)

• agent_name, recommended. Client agent (or SDK) name and version, like my_sdk_0.0.0

Response:

• 200: App instance info updated

  {
    "id": "737112",
    "update_interval_sec": 120
  }

  • id, string. App instance id

  • update_interval_sec, int. Interval for sending update info requests in case of success

Notification events

Request:

curl --header "content-type: application/json" \
     --request POST \
     --url "https://core.push.express/api/r/v2/apps/:app_id/instances/:ic_id/events/notification" \
     --data '
{
    "msg_id": "1828471_1721.7f288d0f-a026-4960-aa04-0c834f07a3ea.5",
    "event": "clicked"
}
'

Body params:

• msg_id, required. Message id (for FCM transport, get from px.msg_id data filed)

• event, required. Event name, one of:

  • delivered -- if possible, send after the notification has been successfully displayed to the user. Else, after the push message has been received from transport. Or do not send at all on any difficulties

  • clicked -- MUST be sent after the user clicks on the notification

Response:

• 202 Accepted, with no content type and empty body

Lifecycle events

Request:

curl --header "content-type: application/json" \
     --request POST \
     --url "https://core.push.express/api/r/v2/apps/:app_id/instances/:ic_id/events/lifecycle" \
     --data '
{
    "event": "onscreen"
}
'

Body params:

• event, required. Event name, one of:

  • onscreen -- app opened (appeared on the screen)

  • background -- app gone to background (disappeared from screen)

  • closed -- app closed (if can be detected)

Response:

• 202 Accepted, with no content type and empty body

Error handling

All HTTP response codes above 400 MUST be considered as error.

In general, errors do not require attention and do not need to be handled in any way.

There are two types of errors.

• Backend errors, will always have content-type: application/json header and json response body

  Example: {"message": "validation error: ..."}

• Other errors from proxy servers, load balancers, etc. There may or may not be some explanation in response body.

  Example: HTTP 504 Gateway Timeout, with empty response body