Filter results by

Monetize device data usage

Device type owners have the option to monetize the data that is sent between their device types and ARTIK Cloud or between ARTIK Cloud and a third-party cloud. They do this by defining Monetization Tiers for a device type in the Developer Dashboard. Monetization Tiers establish a daily message quota that an end user of a device can make a one-time payment to bypass.

This article explains the basics of Monetization setup and how application developers can identify and support Monetization plans.

Monetization basics

Monetization Tiers can be defined for any device type that is published, including Cloud Connectors. You must be an administrator of your organization to create Monetization Tiers.

To define Monetization Tiers, click on a device type and then the "Monetization" link in the left nav menu. Click the "New Monetization Plan" button on the page.

Upgrade device plan

On this page, you set a quota and price to define two Monetization Tiers: Free and Premium. The Free Tier includes a daily quota of free data messages or Actions that these devices can send/receive. The Premium Tier offers the end user a one-time payment to bypass this daily quota for an unlimited number of messages/Actions.

Message quotas are counted differently for native device types and for Cloud Connector device types. Learn more.

On each day that the quota is exceeded, the device user receives an email notification from ARTIK Cloud that offers the option to upgrade to the Premium Tier. The user is directed to use the device again from any app powered by ARTIK Cloud and to follow the prompts to upgrade.

Premium Tiers apply to any users who are sharing the device.

On the next page, you will be prompted to enter bank account information and validate your identity to receive usage fee payouts. ARTIK Cloud handles payments through Stripe on the last day of each month.

Upgrade device plan

After submitting your Monetization plan, the ARTIK Cloud team will send you a contract to sign. This will activate your plan. Until the Monetization plan is approved, the device type can still be used without Monetization.

By default, device type owners receive 70% of Monetization revenue. ARTIK Cloud receives 30%.

Once approved, Monetization Tiers cannot be edited. However, they can be replaced by new Monetization Tiers that you submit for approval. Any end user on the previous Monetization Tiers will remain using those Tiers.

Identify devices using Monetization

An application developer can check if a device or device type is on a Monetization plan using one of the following ways.

Check device type

Make the following call to check if a device type has a Monetization plan. See the API reference for more details.

1
GET /pricing/devicetypes/<deviceTypeID>/pricingtiers?latest=true&status=APPROVED

If the pricingTiers field in the response is empty, the device type is not on a Monetization plan. Otherwise, pricingTiers will be populated with tiers as below. The first and second objects have type corresponding to free and paid plans, respectively.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
 "data" : { 
   "did":"adbcd",
   "pricingTiers":[
     {
        "type": "count",
        "tiers":[
          {
             "ptid":"uniqueTierId",
             "type":"free",
             "name":"basic",
             "description":"Free tier",
             "messageLimit":100,
             "interval":"DAILY",
          },
          {
             "ptid":"uniqueTierId",
             "type":"paid",
             "name":"premium",
             "description":"Paid tier",
             "cost":"9.99",
             "messageLimit":-1,
             "interval":"DAILY",
          }
        ],
        "contactInfo":{ 
           "email":"abc@gmail.com",
           "phone":"986-876-9876"
            },
        "version":1,
        "status":"APPROVED",
        "comments" : "This is Approved."
        "revenueSharePercent":70
      }
   ]
 }
}

Check device directly

Make the following call. See the API reference for more details.

1
GET /pricing/devices/<deviceID>/pricingtiers?active=true

If the pricingTiers field in the response is empty, the device type is not on a Monetization plan. Otherwise, pricingTiers will be populated with the Monetization Tier being used by the device.

If the device is on the Free Tier, as below, an application developer can implement the flow to upgrade the device.

The below response indicates that the device type is using Monetization Tiers and that the device itself is on the Free Tier, with a daily message quota of 100.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
 "data" : { 
   "did":"adbcd",
   "pricingTiers":[ 
      { 
         "ptid":"uniqueTierId",
         "type":"free",
         "name":"basic",
         "description":"Free tier",
         "messageLimit":100,
         "interval":"DAILY",
         "active":true
      }
   ]
 }
}

Support Monetization in an application

When an end user exceeds the message quota set by a device's Free Tier, data messages and Actions can no longer be sent/received. An application developer can follow these steps to add functionality that allows the end user to pay to continue service.

An end user who deletes a device on a Monetization plan and later reconnects the device must pay to upgrade again.

When a user tries to delete a device, your application should check if the device has a Monetization plan and present a warning that if the device is deleted, its Monetization plan will be lost until the device is reconnected and a new payment is made.

Android developers must set javascriptEnabled to true in WebView for the upgrade flow to work.

Step 1: Detect message quota has been reached

Detect a failure triggered by an API call that indicates the daily Free Tier quota has been reached. The HTTP response will have error code 429, and the returned header and response body will look like this:

1
2
3
4
5
x-quota-device-limits: 10/9
x-quota-device-reset: 1497571200000/1497657600000
x-quota-max-payload-size: 1024
x-quota-organization-limits: 10/250000
x-quota-organization-reset: 1498608000000/1498694400000
1
{"error":{"code":429,"message":"Plan quota exceeded for device e15661370ae74d98a155121f8fe5bdbc. Reason: Daily message limit.","id":"4195a2abfe734fe39326c4d864e3d635"}}

In the above header, x-quota-device-limits indicates that the device plan has 9 free messages/Actions per day. The API call fails when sending/receiving the 10th message/Action. See Monetization response header for more details.

Step 2: Obtain upgrade URL

The application prompts the user to make an optional one-time payment to continue using ARTIK Cloud services. After the user chooses to upgrade, the app makes an API call like the following:

1
GET /pricing/devices/<deviceID>/revenueshare/upgradepath?action=upgrade

The response contains a URL like the following:

1
2
3
4
5
{
 "data" :{
  "url":"my.artik.cloud/payment/upgrade/<one-time-use-token>"
  }
}

Step 3: Start a web session

The application loads the URL in a browser to start a web session. The URL is formed by appending the parameter redirect_uri to the URL obtained in Step 2. For example, if the redirect URI is "com.example.upgradedevice://callback", the URL loaded in the web browser will be the following:

1
my.artik.cloud/payment/upgrade/<one-time-use-token>?redirect_uri=com.example.upgradedevice://callback

Note that the application must be able to catch the callback at the specified redirect URI.

Step 4: End user upgrades Monetization Tier

In the web session, the end user goes through the upgrade flow to finish the payment. Here is an example:

Upgrade device plan Upgrade device plan

Step 5: Catch the callback after upgrading

Once the upgrade flow is finished, the browser is redirected to the URI with a status:

1
com.example.upgradedevice://callback?status=accepted

The status can be accepted, declined, or failed. The app decides what to do next based on the status received. For instance, it can make API calls to send and receive messages/Actions, or restart to upgrade again.

How messages are counted

Messages count toward daily quotas in the following scenarios:

Native device types

  • Data messages received by ARTIK Cloud from the device
  • Actions sent from ARTIK Cloud to the device

Cloud Connector device types

  • All requests received by an external cloud from ARTIK Cloud
    • Requests from ARTIK Cloud to the external cloud to get data
    • Requests from ARTIK Cloud to the external cloud to send Actions to the device

APIs relevant to message quotas

ARTIK Cloud APIs will count toward daily message quotas when:

Monetization response header

If a device type has a Monetization plan, the following two fields will appear in the HTTP response header:

1
2
x-quota-device-limits: 10/9
x-quota-device-reset: 1498608000000/1498694400000

x-quota-device-limits displays the device's current daily transactions count and the device type's daily transactions limit (specified in its Free Tier), respectively.

x-quota-device-reset displays the time window for the daily device counter. The values represent the timestamp (in milliseconds from epoch) of start and end of day, respectively.