eSIM Integration - Boxo Documentation

Boxo Platform and Boxo SDK

In this section we will look at some additional integration details (such as user’s locale) when working with Boxo Platform and Boxo SDK.

Payment Payload

Here is the payload that Boxo will send via platform to host app backend.

{
  "currency": "CAD",
  "amount": "20.00",
  "subtotal_amount": "20.00",
  "shipping_amount": "0.00",
  "discount_amount": "0.00",
  "tax_title": "",
  "tax_amount": "5.00",
  "taxes_included": false,
  "note": "",
  "miniapp_order_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
  "hostapp_user_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
  "custom_attributes": {
    "location": {
      "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
      "code": "ES",
      "title": "Spain",
      "type": "COUNTRY",
      "is_global": false
    },
    "provider_net_price": {
      "amount": "10.00",
      "currency": "CAD"
    },
    "data": 1024,
    "duration": 7,
    "order_type": "ACTIVATION"
  }
}

Locale

Host app can provide language during initial launch and miniapp will be able to retrieve latest language settings.

Appboxo.setConfig(Config.Builder().setClientId().setLanguage("en").build()))

Closing miniapp and landing on Home page on next launch

In order to land on Home page each time miniapp is closed and reopened, a saveState=false can be passed. This behavior is available in versions starting from v0.1.4.

For example:

Appboxo.openMiniapp({ appId: appId, saveState: false });

Deeplinks

The deeplink URL should include miniapp id and the relevant URL route, if needed to land user on a specific page.

User will first deeplink to host app, then in host app it parses the deeplink and obtains the miniapp ID and the path to the page.

Open the homepage of the miniapp

const appId = "<app_id>"  // Get miniapp appId from deeplink
Appboxo.closeMiniapp({ appId: appId });
Appboxo.openMiniapp({ appId: appId, saveState: false });

Open a specific page within the miniapp

const appId = "<app_id>"  // Get miniapp appId from deeplink
Appboxo.closeMiniapp({ appId: appId });
Appboxo.openMiniapp({ appId: appId, data: {'deeplink': '/help'}, saveState: false });
// Deeplink contains root slash, path and query params. Example: '/path?id=123'

Available from SDK version v0.1.6 (Capacitor v5) and v0.2.4 (Capacitor v6).

Appboxo.setConfig({ clientId: clientId, showAboutPage: false }); // By default showAboutPage is true

Returning user who has NOT purchased an eSIM will launch into Explore page. Otherwise, will launch Homepage

Appboxo.openMiniapp({ appId: appId, saveState: false, data: {havePurchasedSims: false } });

Caching

Miniapp config is cached for 60 seconds. Logo and other related miniapp configuration changes should be reflected on next launch after 60 seconds have passed.

Android compatibility check enhancement

Available from SDK version v0.3.0 for Capacitor v6.

Instead of performing model check against a compatible device list, Android SDK will perform eSIM compatibility check using native method and pass on the result to eSIM miniapp.

The feature is supported inside the SDK, no code change needed on host app side.

iOS direct installation

Here is an example of implementation of eSIM direct installation, sample code is also available here.

// JS SDK call AppBoxoEsimDirectInstall with direct install URL parameter
// SDK will check iOS version and open given URL
if #available(iOS 17.4, *) {
    guard let url = URL(string: url) else { return }

    if UIApplication.shared.canOpenURL(url) {
      UIApplication.shared.open(url)
    }
}

Capacitor plugin

Capacitor plugin can be downloaded here. Example code reference can be viewed here. Latest version: v0.1.1 (includes changes to support play instruction video on Install Now page).

Webhooks

Here are examples payloads for various webhooks that eSIM Miniapp BE will send, if you have provided use with the webhook URL.

eSIM backend will use hostapp_client_id and hostapp_client_secret configured in Boxo Platform and they will be passed as basic auth in Authorization header along with all requests. You can use this implement authentication for your webhook endpoint.

eSIM order success

This event is fired when user successfully purchases a new eSIM or tops up existing eSIM.

{
  "created": "2024-07-31T03:06:58Z",
  "type": "order.succeeded",
  "data": {
    "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "external_source_payment_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
    "order_type": "ACTIVATION",
    "user_id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "plan": {
      "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
      "title": "5GB for 30 Days",
      "location": {
        "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
        "code": "ES",
        "title": "Spain",
        "type": "COUNTRY",
        "is_global": false
      }
    },
    "sim": {
      "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
      "iccid": "891004234814455936"
    },
    "provider_net_price": {
      "amount": "10.00",
      "currency": "USD"
    },
    "provider_net_local_price": {
      "amount": "15.00",
      "currency": "CAD"
    },
    "subtotal": {
      "amount": "30.00",
      "currency": "CAD"
    },
    "tax": {
      "amount": "5.00",
      "currency": "CAD"
    },
    "total": {
      "amount": "35.00",
      "currency": "CAD"
    }
  }
}

eSIM activated

This event is fired when eSIM activates for the first time.

{
  "created": "2024-07-31T03:06:58Z",
  "type": "sim.activated",
  "data": {
    "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "user_id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "iccid": "891004234814455936",
    "data_remaining": 1024,
    "data_total": 5120,
    "activated": "2024-11-25T15:45:13Z",
    "expired": null,
    "subscriptions": [
      {
        "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
        "plan": {
          "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
          "title": "5GB for 30 Days"
        },
        "data_remaining": 1024,
        "status": "ACTIVE"
      }
    ]
  }
}

eSIM expired

This event is fired when eSIM has expired.

{
  "created": "2024-07-31T03:06:58Z",
  "type": "sim.expired",
  "data": {
    "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "user_id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "iccid": "891004234814455936",
    "data_remaining": 1024,
    "data_total": 5120,
    "activated": "2024-11-25T15:45:13Z",
    "expired": "2024-11-25T15:45:13Z",
    "subscriptions": [
      {
        "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
        "plan": {
          "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
          "title": "5GB for 30 Days"
        },
        "data_remaining": 1024,
        "status": "EXPIRED"
      }
    ]
  }
}

eSIM data zero

This event is fired when eSIM data remaining reaches 0.

{
  "created": "2024-07-31T03:06:58Z",
  "type": "sim.data_zero",
  "data": {
    "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "user_id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "iccid": "891004234814455936",
    "data_remaining": 0,
    "data_total": 5120,
    "activated": "2024-11-25T15:45:13Z",
    "expired": "2024-11-25T15:45:13Z",
    "subscriptions": [
      {
        "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
        "plan": {
          "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
          "title": "5GB for 30 Days"
        },
        "data_remaining": 0,
        "status": "ACTIVE"
      }
    ]
  }
}

eSIM data running low

This event is fired when eSIM data has been used 75% or 90%.

{
  "created": "2024-07-31T03:06:58Z",
  "type": "sim.data_low",
  "data": {
    "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "user_id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "iccid": "891004234814455936",
    "data_remaining": 256,
    "data_total": 5120,
    "activated": "2024-11-25T15:45:13Z",
    "expired": null,
    "subscriptions": [
      {
        "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
        "plan": {
          "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
          "title": "5GB for 30 Days"
        },
        "data_remaining": 256,
        "status": "ACTIVE"
      }
    ]
  }
}

Webhook Simulator

This endpoint allows to simulate various webbhooks sent by eSIM backend. Webhook simulator is available at <esim-backend-url>/api/v1/sources/<hostapp_name>/webhook/simulator/.

Here as an example request to webhook simulator and it’s payload:

curl --location 'https://esim-staging.shopboxo.io/api/v1/sources/<hostapp_name>/webhook/simulator/' \
--header 'Content-Type: application/json' \
--data '{
    "event_type": "order.succeeded",
    "iccid": "893000000000057339",
    "reference": "06b66222-4ff4-4056-803b-dc81c74fcbdc"
}'

{
    "event_type": "order.succeeded",
    "iccid": "893000000000057339",
    "reference": "06b66222-4ff4-4056-803b-dc81c74fcbdc"
}

On this page

Boxo Platform and Boxo SDK
Payment Payload
Locale
Closing miniapp and landing on Home page on next launch
Deeplinks
Hide About from Menu
Returning user who has NOT purchased an eSIM will launch into Explore page. Otherwise, will launch Homepage
Caching
Android compatibility check enhancement
iOS direct installation
Capacitor plugin
Webhooks
eSIM order success
eSIM activated
eSIM expired
eSIM data zero
eSIM data running low
Webhook Simulator

Boxo Platform and Boxo SDK

In this section we will look at some additional integration details (such as user’s locale) when working with Boxo Platform and Boxo SDK.

Payment Payload

Here is the payload that Boxo will send via platform to host app backend.

{
  "currency": "CAD",
  "amount": "20.00",
  "subtotal_amount": "20.00",
  "shipping_amount": "0.00",
  "discount_amount": "0.00",
  "tax_title": "",
  "tax_amount": "5.00",
  "taxes_included": false,
  "note": "",
  "miniapp_order_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
  "hostapp_user_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
  "custom_attributes": {
    "location": {
      "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
      "code": "ES",
      "title": "Spain",
      "type": "COUNTRY",
      "is_global": false
    },
    "provider_net_price": {
      "amount": "10.00",
      "currency": "CAD"
    },
    "data": 1024,
    "duration": 7,
    "order_type": "ACTIVATION"
  }
}

Locale

Host app can provide language during initial launch and miniapp will be able to retrieve latest language settings.

Appboxo.setConfig(Config.Builder().setClientId().setLanguage("en").build()))

Closing miniapp and landing on Home page on next launch

In order to land on Home page each time miniapp is closed and reopened, a saveState=false can be passed. This behavior is available in versions starting from v0.1.4.

For example:

Appboxo.openMiniapp({ appId: appId, saveState: false });

Deeplinks

The deeplink URL should include miniapp id and the relevant URL route, if needed to land user on a specific page.

User will first deeplink to host app, then in host app it parses the deeplink and obtains the miniapp ID and the path to the page.

Open the homepage of the miniapp

const appId = "<app_id>"  // Get miniapp appId from deeplink
Appboxo.closeMiniapp({ appId: appId });
Appboxo.openMiniapp({ appId: appId, saveState: false });

Open a specific page within the miniapp

const appId = "<app_id>"  // Get miniapp appId from deeplink
Appboxo.closeMiniapp({ appId: appId });
Appboxo.openMiniapp({ appId: appId, data: {'deeplink': '/help'}, saveState: false });
// Deeplink contains root slash, path and query params. Example: '/path?id=123'

Available from SDK version v0.1.6 (Capacitor v5) and v0.2.4 (Capacitor v6).

Appboxo.setConfig({ clientId: clientId, showAboutPage: false }); // By default showAboutPage is true

Returning user who has NOT purchased an eSIM will launch into Explore page. Otherwise, will launch Homepage

Appboxo.openMiniapp({ appId: appId, saveState: false, data: {havePurchasedSims: false } });

Caching

Miniapp config is cached for 60 seconds. Logo and other related miniapp configuration changes should be reflected on next launch after 60 seconds have passed.

Android compatibility check enhancement

Available from SDK version v0.3.0 for Capacitor v6.

Instead of performing model check against a compatible device list, Android SDK will perform eSIM compatibility check using native method and pass on the result to eSIM miniapp.

The feature is supported inside the SDK, no code change needed on host app side.

iOS direct installation

Here is an example of implementation of eSIM direct installation, sample code is also available here.

// JS SDK call AppBoxoEsimDirectInstall with direct install URL parameter
// SDK will check iOS version and open given URL
if #available(iOS 17.4, *) {
    guard let url = URL(string: url) else { return }

    if UIApplication.shared.canOpenURL(url) {
      UIApplication.shared.open(url)
    }
}

Capacitor plugin

Capacitor plugin can be downloaded here. Example code reference can be viewed here. Latest version: v0.1.1 (includes changes to support play instruction video on Install Now page).

Webhooks

Here are examples payloads for various webhooks that eSIM Miniapp BE will send, if you have provided use with the webhook URL.

eSIM order success

This event is fired when user successfully purchases a new eSIM or tops up existing eSIM.

{
  "created": "2024-07-31T03:06:58Z",
  "type": "order.succeeded",
  "data": {
    "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "external_source_payment_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
    "order_type": "ACTIVATION",
    "user_id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "plan": {
      "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
      "title": "5GB for 30 Days",
      "location": {
        "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
        "code": "ES",
        "title": "Spain",
        "type": "COUNTRY",
        "is_global": false
      }
    },
    "sim": {
      "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
      "iccid": "891004234814455936"
    },
    "provider_net_price": {
      "amount": "10.00",
      "currency": "USD"
    },
    "provider_net_local_price": {
      "amount": "15.00",
      "currency": "CAD"
    },
    "subtotal": {
      "amount": "30.00",
      "currency": "CAD"
    },
    "tax": {
      "amount": "5.00",
      "currency": "CAD"
    },
    "total": {
      "amount": "35.00",
      "currency": "CAD"
    }
  }
}

eSIM activated

This event is fired when eSIM activates for the first time.

{
  "created": "2024-07-31T03:06:58Z",
  "type": "sim.activated",
  "data": {
    "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "user_id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "iccid": "891004234814455936",
    "data_remaining": 1024,
    "data_total": 5120,
    "activated": "2024-11-25T15:45:13Z",
    "expired": null,
    "subscriptions": [
      {
        "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
        "plan": {
          "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
          "title": "5GB for 30 Days"
        },
        "data_remaining": 1024,
        "status": "ACTIVE"
      }
    ]
  }
}

eSIM expired

This event is fired when eSIM has expired.

{
  "created": "2024-07-31T03:06:58Z",
  "type": "sim.expired",
  "data": {
    "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "user_id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "iccid": "891004234814455936",
    "data_remaining": 1024,
    "data_total": 5120,
    "activated": "2024-11-25T15:45:13Z",
    "expired": "2024-11-25T15:45:13Z",
    "subscriptions": [
      {
        "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
        "plan": {
          "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
          "title": "5GB for 30 Days"
        },
        "data_remaining": 1024,
        "status": "EXPIRED"
      }
    ]
  }
}

eSIM data zero

This event is fired when eSIM data remaining reaches 0.

{
  "created": "2024-07-31T03:06:58Z",
  "type": "sim.data_zero",
  "data": {
    "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "user_id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "iccid": "891004234814455936",
    "data_remaining": 0,
    "data_total": 5120,
    "activated": "2024-11-25T15:45:13Z",
    "expired": "2024-11-25T15:45:13Z",
    "subscriptions": [
      {
        "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
        "plan": {
          "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
          "title": "5GB for 30 Days"
        },
        "data_remaining": 0,
        "status": "ACTIVE"
      }
    ]
  }
}

eSIM data running low

This event is fired when eSIM data has been used 75% or 90%.

{
  "created": "2024-07-31T03:06:58Z",
  "type": "sim.data_low",
  "data": {
    "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "user_id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
    "iccid": "891004234814455936",
    "data_remaining": 256,
    "data_total": 5120,
    "activated": "2024-11-25T15:45:13Z",
    "expired": null,
    "subscriptions": [
      {
        "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
        "plan": {
          "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
          "title": "5GB for 30 Days"
        },
        "data_remaining": 256,
        "status": "ACTIVE"
      }
    ]
  }
}

Webhook Simulator

This endpoint allows to simulate various webbhooks sent by eSIM backend. Webhook simulator is available at <esim-backend-url>/api/v1/sources/<hostapp_name>/webhook/simulator/.

Here as an example request to webhook simulator and it’s payload:

curl --location 'https://esim-staging.shopboxo.io/api/v1/sources/<hostapp_name>/webhook/simulator/' \
--header 'Content-Type: application/json' \
--data '{
    "event_type": "order.succeeded",
    "iccid": "893000000000057339",
    "reference": "06b66222-4ff4-4056-803b-dc81c74fcbdc"
}'

{
    "event_type": "order.succeeded",
    "iccid": "893000000000057339",
    "reference": "06b66222-4ff4-4056-803b-dc81c74fcbdc"
}

On this page

Boxo Platform and Boxo SDK
Payment Payload
Locale
Closing miniapp and landing on Home page on next launch
Deeplinks
Hide About from Menu
Returning user who has NOT purchased an eSIM will launch into Explore page. Otherwise, will launch Homepage
Caching
Android compatibility check enhancement
iOS direct installation
Capacitor plugin
Webhooks
eSIM order success
eSIM activated
eSIM expired
eSIM data zero
eSIM data running low
Webhook Simulator

​Boxo Platform and Boxo SDK

​Payment Payload

​Locale

​Closing miniapp and landing on Home page on next launch

​Deeplinks

​Hide About from Menu

​Returning user who has NOT purchased an eSIM will launch into Explore page. Otherwise, will launch Homepage

​Caching

​Android compatibility check enhancement

​iOS direct installation

​Capacitor plugin

​Webhooks

​eSIM order success

​eSIM activated

​eSIM expired

​eSIM data zero

​eSIM data running low

​Webhook Simulator

​Boxo Platform and Boxo SDK

​Payment Payload

​Locale

​Closing miniapp and landing on Home page on next launch

​Deeplinks

​Hide About from Menu

​Returning user who has NOT purchased an eSIM will launch into Explore page. Otherwise, will launch Homepage

​Caching

​Android compatibility check enhancement

​iOS direct installation

​Capacitor plugin

​Webhooks

​eSIM order success

​eSIM activated

​eSIM expired

​eSIM data zero

​eSIM data running low

​Webhook Simulator

Boxo Platform and Boxo SDK

Payment Payload

Locale

Closing miniapp and landing on Home page on next launch

Deeplinks

Hide About from Menu

Returning user who has NOT purchased an eSIM will launch into Explore page. Otherwise, will launch Homepage

Caching

Android compatibility check enhancement

iOS direct installation

Capacitor plugin

Webhooks

eSIM order success

eSIM activated

eSIM expired

eSIM data zero

eSIM data running low

Webhook Simulator

Boxo Platform and Boxo SDK

Payment Payload

Locale

Closing miniapp and landing on Home page on next launch

Deeplinks

Hide About from Menu

Returning user who has NOT purchased an eSIM will launch into Explore page. Otherwise, will launch Homepage

Caching

Android compatibility check enhancement

iOS direct installation

Capacitor plugin

Webhooks

eSIM order success

eSIM activated

eSIM expired

eSIM data zero

eSIM data running low

Webhook Simulator