# SDK API specs

**PushExpress -- SDK and application instances API reference**

Version date: 05 Feb 2024

***

## Application flow

### 1. Application startup

Clients (app developers) MUST do some initialization in application code (see [SDK interface](#sdk-interface)).

Usually, they should provide `app_id` (which MUST be stored in app local storage) and SDK flow `activation flag` (just in-memory flag).

If no valid `app_id` found, or SDK flow is not activated by developer, further steps SHALL NOT be done.

#### 1.1. Generate some local-persistent installation-token (`ic_token`)

Clients need to have some independent globally-unique installation id, even if no internet access available.

This id often used in multiple ad-platforms, and very useful for clients who do not have their own user base with their own ids.

We suggest to use UUIDv4 or UUIDv7 as easily accessible on any modern programming languages.

Of course, clients can generate and store this ID on their own, but it is more convenient to do this at the SDK level.

So, you need:

1. Generate UUIDv4 (or UUIDv7) to use as `ic_token`
2. Store `ic_token` in local storage.

```kotlin
import java.util.UUID

const val icToken = UUID.randomUUID().toString()

// store icToken in app restart-persistent local storage!!!
```

#### 1.2. Check if it is first start after installation

Access some variable from app persistent local storage, for example `ic_id` (PushExpress App Instance Id).

If non-nil and non-empty variable found, assume it is existing install and go to section **1.3.**

Else, do the following steps:

1. Get `ic_id` as specified here: [get id for new app instance](##get-id-for-new-app-instance)
2. In case of any error (non-200 response or invalid response object), retry *infinitely* with exponential backoff algorithm, better with random initial value between 1-5s, capped at maximum delay of about 120s
3. Store aquired `ic_id` in local storage. Storage MUST be resistant to app updates and MUST be cleared on app removal. Storage SHOULD not overlap with existing app storages (for use as library). If it is not possible, use a more distinguishable field name (`px_ic_id`)
4. Go to section **2.**

#### 1.3. Startup on existing installation

As soon as possible after app startup issue first update app info request as described in section **2.**

Periodically update app info with received `update_interval_sec` interval.

### 2. Update app info

1. Gather some device and app info params like FCM token, country, language, timezone, app onscreen count and time, etc
2. Issue [update app info](##update-app-instance-info) request (only some fields are required, other can be updated later)
3. In case of any error (non-200 response or invalid response object), retry *infinitely* with exponential backoff algorithm, better with random initial value between 1-5s, capped at maximum delay of about 120s
4. Repeat [update app info](##update-app-instance-info) request with received `update_interval_sec` interval

Note: it's better to update current app state (on screen/background) and send actual `onscreen_count` and `onscreen_sec`.

### 3. Subscribe and listen transport messages

Subscribe for transport channel (for example, Firebase Cloud Messaging).

#### 3.1. Firebase Cloud Messaging transport

Incoming message id MUST be registered by extracting data field `px.msg_id` and [send it](##notification-events) in `clicked` event.

Notification MUST be displayed with title, body, image and icon, based on standard Firebase `notification` fields. Or manually by corresponding `px.*` fields in `data`.

After notification has been displayed, `delivered` event [SHOULD be send](##notification-events). If not possible to detect displaying, send it after FCM message has been received.

FCM transport message format:

```json
{
  "notification": {
    "title": "hello there",
    "body": "hello",
    "image": "https://avatars.githubusercontent.com/u/108216418",
    "icon": "https://avatars.githubusercontent.com/u/108216418"
  },
  "data": {
    "px.msg_id": "1828471_1721.7f288d0f-a026-4960-aa04-0c834f07a3ea.5",
    "px.title": "hello there",
    "px.body": "hello",
    "px.image": "https://avatars.githubusercontent.com/u/108216418",
    "px.icon": "https://avatars.githubusercontent.com/u/108216418"
  }
}
```

### 4. Gather app lifecycle (on screen, background) events

Application startups and screen time SHOULD be tracked and saved in local storage, for sending correct `onscreen_count` and `onscreen_sec` fields in [update app info](##update-app-instance-info) request.

App [lifecycle events](##lifecycle-events) MAY be sent when app is shown on screen or goes to background.

## SDK interface

Below is an example of Kotlin SDK interface:

```kotlin
import com.pushexpress.sdk.main.SdkPushExpress

const val PUSHEXPRESS_APP_ID = "####-######"

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        SdkPushExpress.initialize(PUSHEXPRESS_APP_ID)
        SdkPushExpress.setExternalId("user_registration_id_1234") // optional
        SdkPushExpress.setTag("ad_id", getAdvertisingIdOrEmpty()) // optional
        SdkPushExpress.setTag("offer", "google_ads_12321") // optional
        SdkPushExpress.activate() // Don't forget to activate SDK workflow!
}
```

## API v2 reference

### 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