# SDK API v2

## Get id for new app instance

Request:

```bash
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

  ```json
  {
    "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:

```bash
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):

  ```kotlin
  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

  ```json
  {
    "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:

```bash
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:

```bash
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