InAppBilling Module

Description

The InAppBilling module allows you to access the Android In-App Billing mechanism.

Getting Started

View the Using Titanium Modules document for instructions on getting started with using this module in your application.

Note that there may be two versions of this module available to you, one for use with pre-1.8.0.1 SDKs and one for use with 1.8.0.1 or newer. In your tiapp.xml file, make sure that you specify the version of the module that corresponds to the version of Titanium Mobile SDK that you are targeting. For Appcelerator modules, specify the 1.X version of the module if building for versions of Titanium Mobile SDK prior to 1.8.0.1 and specify the 2.X version of the module if building for versions of Titanium Mobile SDK 1.8.0.1 or newer.

The In-App Billing process using this module is as follows:

First you must call startBillingService(), this initializes the process. Two events are fired from this call: ON_BIND_EVENT and ON_CONNECT_EVENT. Once the ON_CONNECT_EVENT has fired, the module is ready to send requests to the Android Market. There are 5 different request methods:

-checkBillingSupported()
-requestPurchase()
-getPurchaseInformation()
-confirmNotifications() 
-restoreTransactions()

Three events can be fired in response to these requests:

RESPONSE_EVENT 
PURCHASE_STATE_CHANGED_EVENT
NOTIFY_EVENT.

To use the Signature Verification code included in the module, you must also set the Public Key using

-setPublicKey()

If this is not set, the process will function but will not internally verify any Market responses.

Accessing the InAppBilling Module

To access this module from JavaScript, you would do the following:

var InAppBilling = require('ti.inappbilling');

Functions

startBillingService()

Initializes the Billing Service which will be used to send messages to the Android Market. When the Billing Service is bound to the Market Service, an ON_BIND_EVENT e is fired. When the Billing Service connects to the Market service, an ON_CONNECT_EVENT is fired, and the Billing Service can now be used for other requests. This MUST be called before any of the 5 request functions.

checkBillingSupported()

Sends a Check Billing Supported request to the Market. This will trigger one synchronous response, a RESPONSE_EVENT. This request will not trigger any asynchronous responses.

requestPurchase({ productId: String productId0, developerPayload: String developerPayload0 })

Sends a Request Purchase request to the Market, for the specified productId with the specified (optional) developerPayload. This will prompt the Android Market Confirmation window to appear for the specified product. This will trigger one synchronous response, a RESPONSE_EVENT.

This request will also trigger two asynchronous responses: one NOTIFY_EVENT and one RESPONSE_EVENT.

getPurchaseInformation({ notificationIds: String[] notificationIds0})

Sends a Get Purchase Information request to market, for the specified String notificationIds. This should be called after an In-App Notify response is recieved, and will request more detailed transaction information. This will trigger one synchronous response, a RESPONSE_EVENT.

This request will also trigger two asynchronous responses: one PURCHASE_STATE_CHANGED_EVENT and one RESPONSE_EVENT.

confirmNotifications({ notificationIds: String[] notificationIds0 })

Sends a Confirm Notifications request to the market, for the specified String notificationIds. This is called to confirm with the Market the delivery of the purchases signified by the notificationIds passed in. This will trigger one synchronous response, a RESPONSE_EVENT.

This request will trigger one asynchronous response, a RESPONSE_EVENT.

restoreTransactions()

Sends a restore Transactions request to the market. This will deliver the user's transaction history for purchases with this application. Should be called only when the application is installed/re-installed. This will trigger one synchronous response, a RESPONSE_EVENT.

This request will also trigger two asynchronous responses: one PURCHASE_STATE_CHANGED_EVENT and one RESPONSE_EVENT.

setPublicKey(String publicKey)

Sets the key to be used for signature verification (Key is found in Android Market profile information)

Properties

Ti.InAppBilling.SUCCESS int

Success state in Billing Service binding.

Ti.InAppBilling.FAILED int

Fail state in Billing Service binding.

Ti.InAppBilling.SECEXCEPTION int

Security Exception state in Billing Service binding.

Ti.InAppBilling.RESULT_OK int

 OK message from a Response Code notification.

Ti.InAppBilling.RESULT_USER_CANCELED int

 User Canceled message from a Response Code notification.

Ti.InAppBilling.RESULT_SERVICE_UNAVAILABLEint

 User Canceled message from a Response Code notification.

Ti.InAppBilling.RESULT_BILLING_UNAVAILABLEint

 Billing Unavailable message from a Response Code notification.

Ti.InAppBilling.RESULT_ITEM_UNAVAILABLE int

Item Unavailable message from a Response Code notification.

Ti.InAppBilling.RESULT_DEVELOPER_ERROR int

Developer Error message from a Response Code notification.

Ti.InAppBilling.RESULT_ERROR int

Result Error message from a Response Code notification

Ti.InAppBilling.SIGNATURE_VERIFIED int

Success response from signature verification.

Ti.InAppBilling.NULL_DATA int

Null data response from signature verification (occurs if there is no signed data sent in
Purchase State Changed notification).

Ti.InAppBilling.SIGNATURE_ERROR int

Error response from signature verification (occurs if the signature is incorrect and cannot
be verified).

Ti.InAppBilling.UNKNOWN_NONCE int

Unknown Nonce response from signature verification (occurs if the nonce returned from the Market
differs from any that have been sent, the message is thus insecure, see Android Documentation).

Ti.InAppBilling.PUBLIC_KEY_NULLint

Public Key null response from signature verification (occurs if setPublicKey has not been called).

Events

ON_BIND_EVENT

Event e is fired when the Billing Service binds with the Market serice, with the property e.result
equal to one of the following:

InAppBilling.SUCCESS
InAppBilling.FAILED
InAppBilling.SECEXCEPTION

ON_CONNECT_EVENT

Event e is fired when the Billing Service connects to the market. This event has no properties,
but signifies that requests can now be made to the Android Market.

NOTIFY_EVENT

Event e is fired when the module receives an asynchronous IN\_APP\_NOTIFY response from the Market. This event has
one property, e.notifyId. This ID can be used for calls to GetPurchaseInformation and confirmNotifications.

PURCHASE_STATE_CHANGED_EVENT

Event e is fired when the module receives an asynchronous PURCHASE\_STATE\_CHANGED response from the market.
This event has 3 properties: first, e.signedData, a JSON String which can be parsed into a JSON object
(see Android documentation: http://developer.android.com/guide/market/billing/billing_reference.html#billing-intents).
Second, e.signature,  this can be used to verify the response recieved. If the Public Key has been set, 
the module will verify automatically. Third, e.result, a int response with one the following possible values:

InAppBilling.SIGNATURE_VERIFIED
InAppBilling.NULL_DATA
InAppBilling.SIGNATURE_ERROR 
InAppBilling.UNKNOWN_NONCE
InAppBilling.PUBLIC\_KEY\_NULL

RESPONSE_EVENT

Event e is fired both from receiving an asynchronous RESPONSE_CODE event and synchronously from each request method. 
This event, has 3 properties: first, e.requestId, a double that provides a unique indicator of the response. Second, 
e.responseCode, an int response with one of the following possible values:

InAppBilling.RESULT_OK
InAppBilling.RESULT_USER_CANCELED
InAppBilling.RESULT_SERVICE_UNAVAILABLE       
InAppBilling.RESULT_BILLING_UNAVAILABLE
InAppBilling.RESULT_ITEM_UNAVAILABLE
InAppBilling.RESULT_DEVELOPER_ERROR
InAppBilling.RESULT_ERROR

Third, e.sync, a boolean value that states whether the event was fired synchronously or not.

Usage

See example and Android documentation.

Author

Developed for Appcelerator by Logical Labs Alexander Conway, Logical Labs

Module History

View the change log for this module.

Feedback and Support

Please direct all questions, feedback, and concerns to info@appcelerator.com.

License

Copyright(c) 2010-2011 by Appcelerator, Inc. All Rights Reserved. Please see the LICENSE file included in the distribution for further details.