In-app purchase SDK Guide(Rev.1.0) 2
Note the following points when using this guide.
The content of this guide may be changed without prior notice.
1 Reprinting or reproducing part or all of this document without prior permission from Seiko Epson
Corporation, or using it for anything but its intended purpose is strictly prohibited.
2 The programs and usages published in this guide is to be used as reference material only. Epson
does not guarantee the rights (including industrial property) of third parties for any damage
incurred. Furthermore, this guide does not provide license for third parties or other companies.
3 Products mentioned in this guide are not intended for use in life support systems or other systems
in which high reliability is required. Therefore, we cannot accept responsibility if the
aforementioned products are used in systems such as those mentioned.
Trademarks
Google, Android, Android Studio, and Chrome are the trademarks or registered trademarks of Google
Inc. in the United States and other countries.
Other product names used herein are also for identification purposes only and may be trademarks of
their respective owners. Epson disclaims any
and all rights in those marks.
©SEIKO EPSON CORAPORATION 2016, All right reserved.
In-app purchase SDK Guide(Rev.1.0) 3
Contents
1. Summary .................................................................................................................................. 4
2. Development Environment ...................................................................................................... 5
3. Embedding the In-app Purchase SDK ..................................................................................... 6
3.1. How to use the SDK .............................................................................................................. 6
4. Summary of In-app Purchases ............................................................................................... 10
4.1. Points to note when using the SDK .................................................................................... 10
4.2. Registering Applications to MOVERIO Apps Market ........................................................ 10
5. In-app Purchase Flow ............................................................................................................ 13
5.1. In-app purchase item - Purchasing items .......................................................................... 14
5.2. In-app purchase item - Consumable items ......................................................................... 15
6. In-app Purchase API .............................................................................................................. 16
6.1. In-app purchase supported/unsupported check API .......................................................... 16
6.2. In-app purchase item - List of items API ........................................................................... 17
6.3. In-app purchase item - Individual purchase details API ................................................... 18
6.4. In-app purchase item - Purchasing items API ................................................................... 19
6.5. In-app purchase item - Consuming items API ................................................................... 21
7. Response code list ................................................................................................................... 22
In-app purchase SDK Guide(Rev.1.0) 4
1. Summary The BT-300 in-app purchase SDK allows you to include an in-app purchase feature that links to
the MOVERIO Apps Market.
The following shows the supported/unsupported in-app purchases for the in-app purchase SDK.
[Supported]
Each purchase (consumable type/non-consumable type)
[Unsupported]
Fixed term purchases
By using the SDK to link with the MOVERIO Apps Market, you can easily introduce in-app
purchases through PayPal (https://www.paypal.com/).
You can also confirm sales from the MOVERIO Apps Market developer’s site.
In-app purchase SDK Guide(Rev.1.0) 5
2. Development Environment The BT-300 uses Android for its system software. This allows you to develop in-app purchase
introduction applications for the BT-300 in the same application development environment as for
Android smart phones.
See other documentation (documents about Android Studio provided by Google) for
information on the development environment.
In-app purchase SDK Guide(Rev.1.0) 6
3. Embedding the In-app Purchase SDK
3.1. How to use the SDK
The following usage method assumes apps are being developed in Android Studio.
1) Display ProjectView in Android Studio, and then select [File] - [New] - [New Module...].
In-app purchase SDK Guide(Rev.1.0) 7
2) Select Import .JAR/.AAR Package.
3) Specify the in-app purchase SDK “inappbillingsdk.aar” file.
In-app purchase SDK Guide(Rev.1.0) 8
4) From the menu, select [File] - [Project Structure...].
5) Click the [Dependencies] tab, click the [+] button, and then select [Module dependency].
In-app purchase SDK Guide(Rev.1.0) 9
6) Select [inappbillingsdk].
This completes setting up the SDK.
In-app purchase SDK Guide(Rev.1.0) 10
4. Summary of In-app Purchases
4.1. Points to note when using the SDK
In the in-app purchase SDK, payments are made through PayPal (https://www.paypal.com/)
linked with the MOVERIO Apps Market. Therefore, you need a MOVERIO Apps Market user
account as well as a PayPal Sandbox account
(https://developer.paypal.com/developer/accounts/) when evaluating.
To use in-app purchases in the in-app purchases SDK, you also need a developer account that
has used "Log in with PayPal" and is linked to a PayPal account.
Please refer “From test your app to app publication” for testing your app.
You may not be able to make in-app purchases temporarily while the MOVERIO Apps Market is
under maintenance.
4.2. Registering Applications to MOVERIO Apps Market
To perform in-app purchases, you need to register the application to the MOVERIO Apps
Market developer's site in advance.
When registering the application, also register the in-app purchase item.
After temporarily saving the app, the in-app purchase item for development becomes available
immediately.
After developing an app that includes in-app purchases, you can execute in-app purchases in
a public environment by applying to release the app in the MOVERIO Apps Market. The ID for
development is also available after applying to publish.
In-app purchase SDK Guide(Rev.1.0) 11
1) Upload the application for which you want to perform in-app purchases. If it has already
been uploaded, open the update screen.
2) Select "BT-300" as the supported model, and then select "YES(Epson SDK)" under In-app
purchases.
In-app purchase SDK Guide(Rev.1.0) 12
3) Register the in-app purchase item.
4) You can delete registered in-app purchase items.
5) By temporarily saving the app, the item ID for development is enabled.
To temporarily save the app, you also need to enter temporary items for each field.
Since the information entered is not publicly available when the app is saved temporarily,
you can enter place holders for the necessary information.
In-app purchase SDK Guide(Rev.1.0) 13
5. In-app Purchase Flow Please use following to use in-app purchase SDK.
■ Checking if in-app purchases are supported/unsupported :
isMvBillingSupported() (the equivalent of Google's isBillingSupported())
■ In-app purchase item - List of items:
getMvPurchases () (the equivalent of Google’s getPurchases())
■ In-app purchase item - Individual purchase details:
getMvSkuDetails() (the equivalent of Google’s getSkuDetails())
■ In-app purchase item - Purchasing items:
getMvBuyIntent() (the equivalent of Google’s getBuyIntent())
■ In-app purchase item - Consumable items:
consumeMvPurchase() (the equivalent of Google’s consumePurchase())
In-app purchase SDK Guide(Rev.1.0) 14
5.1. In-app purchase item - Purchasing items
1. First, use isMvBillingSupported to check whether the MOVERIO Apps Market supports
the BT-300 in-app purchases SDK.
2. The getMvPurchases command acquires the in-app purchases owned by the user.
When the request is handled normally, MOVERIO Apps Market returns the items owned
by the user and the details of the purchase.
3. The getMvSkuDetails command acquires details on the item ID registered in the
MOVERIO Apps Market. When the request is handled normally, MOVERIO Apps Market
returns details of the price and title.
4. If the user does not own the in-app purchase item, the purchasing process of the item
can begin. The getMvBuyIntent command is used to start the purchase.
5. The PendingIntent for displaying the purchasing screen is included in the Bundle
returned by getMvBuyIntent. Use startIntentSenderForResult to start this
PendingIntent.
6. When the purchasing flow is complete, MOVERIO Apps Market sends the purchasing
information that includes the results code to onActivityResult. The purchaseToken,
developerPayload, and so on used to identify the transaction are included in the
purchase information.
In-app purchase SDK Guide(Rev.1.0) 15
5.2. In-app purchase item - Consumable items
The ownership rights for all in-app purchases are maintained by the MOVERIO Apps Market.
When an in-app purchase item is purchased, the item is “Owned” by the user who purchased
it.
Once an item is "Owned", the same item cannot be purchased again. To be purchased again,
the item must be "Consumed".
When the in-app purchase item is "Consumed", the user returns to an "Un-owned" status, and
the previous purchase data is discarded.
It is up to the developer to select whether an in-app purchase item is "Consumable" or
"Non-consumable".
When a "non-consumable" item is purchased once by the user, ownership right is permanently
given to the user.
"Consumable" items can be purchased/used more than once, and the app needs to implement
the "consumption" process.
In-app purchase SDK Guide(Rev.1.0) 16
6. In-app Purchase API This section explains about the following functions that allow you to use applications that support
in-app purchases.
■ Checking if in-app purchases are supported/unsupported:
isMvBillingSupported() (the equivalent of Google's isBillingSupported())
■ In-app purchase item - List of items:
getMvPurchases () (the equivalent of Google’s getPurchases())
■ In-app purchase item - Individual purchase details:
getMvSkuDetails() (the equivalent of Google’s getSkuDetails())
■ In-app purchase item - Purchasing items:
getMvBuyIntent() (the equivalent of Google’s getBuyIntent())
■ In-app purchase item - Consumable items:
consumeMvPurchase() (the equivalent of Google’s consumePurchase())
6.1. In-app purchase supported/unsupported check API
Checks whether or not in-app purchases are available.
■ Import file
com.epson.moverio.inappbillingsdk.Billing
■ Constructor
Billing (Context context)
■ Interface
int isMvBillingSupported()
■ Parameters
None
■ Return value
Execution results 1 (Supported), (0) (Not supported), 2 (Logged out of MOVERIO Apps
Market)
In-app purchase SDK Guide(Rev.1.0) 17
6.2. In-app purchase item - List of items API
You can acquire a list of the in-app purchase items owned by the user.
■ Import file
com.epson.moverio.inappbillingsdk.Billing
■ Constructor
Billing (Context context)
■ Interface
Bundle getMvPurchases (String packageId, String type)
■ Parameters
packageId: Application package name
type: Charge classification: Fixed at In-app purchase (“inapp”)
■ Return value
A “bundle” storing the following data
Key Details Model
RESPONSE_CODE Processing results
code
int
INAPP_PURCHASE_ITEM_LIST Item ID List StringArrayList
INAPP_PURCHASE_DATA_LIST (JSON) Purchase data
list
StringArrayList
INAPP_DATA_SIGNATURE_LIST Signature List StringArrayList
In-app purchase SDK Guide(Rev.1.0) 18
6.3. In-app purchase item - Individual purchase details API
You can acquire details of the registered in-app purchase items.
When acquiring an item for development evaluation, make sure you store the ID for
development in the list and set it as a parameter.
■ Import file
com.epson.moverio.inappbillingsdk.Billing
■ Constructor
Billing (Context context)
■ Interface
Bundle getMvSkuDetails (String packageId, String type, Bundle bundle)
■ Parameters
packageId: Application package name
type: Charge classification: Fixed at In-app purchase (“inapp”)
Bundle: A bundle that stores a list of the "in-app purchase item IDs" in the
"ITEM_ID_LIST".
■ Return value
A “bundle” storing the following data
Key Details Model
RESPONSE_CODE Processing results code int
DETAIL_LIST List of charged items (JSON) StringArrayList
■ Charged items (JSON)
JSON data storing the following data
Key Details
productId In-app purchase item ID
type In-app purchase type
price Price + Currency
price_amount_micros Price in micro units. 1,000,000 micro units = 1 currency unit.
price_currency_code Currency
title In-app purchase item name
In-app purchase SDK Guide(Rev.1.0) 19
6.4. In-app purchase item - Purchasing items API
Setting up in-app purchase items.
User purchases can be started by executing PendingIntent stored in the return value using the
startIntentSenderForResult method. When setting an item ID for development evaluation,
purchase in the PayPal Sandbox.
■ Import file
com.epson.moverio.inappbillingsdk.Billing
■ Constructor
Billing (Context context)
■ Interface
Bundle getMvBuyIntent (String packageId, String productId, String type, String
developerPayload)
■ Parameters
packageId: Application package name
productId: In-app purchase item ID
type: Charge classification: Fixed at In-app purchase (“inapp”)
developerPayload: The text string included and returned in the JSON purchase data
when a purchase is complete.
■ Return value
A “bundle” storing the following data
Key Details Model
RESPONSE_CODE Processing results
code
int
BUY_INTENT PayPal purchase Intent PendingIntent
In-app purchase SDK Guide(Rev.1.0) 20
■ Purchase Intent Results
Key Details Model
RESPONSE_CODE Processing results
code
int
INAPP_PURCHASE_DATA (JSON) Purchase data String
INAPP_DATA_SIGNATURE Signature String
■ JSON Purchase data
JSON data storing the following data
Key Details
orderId Order ID
packageName Application package name
productId In-app purchase item ID
purchaseTime Purchase date/time
purchaseState Purchase status (0: purchase, 1: cancel, 2: error)
developerPayload Purchase information text string
purchaseToken Unique ID generated by pairing the user and the item.
In-app purchase SDK Guide(Rev.1.0) 21
6.5. In-app purchase item - Consuming items API
Consume the in-app purchase items owned by the user.
An error code is returned when the user attempts to consume an item that has already been
consumed or an item that is not purchased.
If your system does not contain unnecessary items, you do not have to execute this API.
■ Import file
com.epson.moverio.inappbillingsdk.Billing
■ Constructor
Billing (Context context)
■ Interface
int consumeMvPurchase (String packageId, String token)
■ Parameters
packageId: Application package name
Token: Token for purchased items (purchaseToken for INAPP_PURCHASE_DATA_LIST)
■ Return value
Execution results 0 (normal value), Others (error)
In-app purchase SDK Guide(Rev.1.0) 22
7. Response code list A list of the response codes used in the MOVERIO in-app purchase SDK.
Response code Value Details
BILLING_RESPONSE_RESULT_OK 0 Completed normally
BILLING_RESPONSE_RESULT_USER_CANCELED 1 User canceled
BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE 2 Market service unavailable
error
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE 3 In-app purchase unavailable
error
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE 4 Item information unavailable
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR 5 Parameter error
BILLING_RESPONSE_RESULT_ERROR 6 Unknown error
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED 7 Item already owned
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED 8 Item not owned