Altova MobileTogether Designer

The preceding topics of this section described the main components of MobileTogether Designer's In-App Purchases mechanism. In this topic, we list and briefly describe the other key components of the mechanism.

Check availability of In-app Purchases service

You can use a function named mt-in-app-purchase-service-started() to check whether the in-app purchase service has been started on the client device. For details, see the topics MobileTogether Extension Functions and Example Project: Availability of In-App Service.

Check app store response to last in-app purchase

The following MobileTogether extension functions can be used to check the success of the last request to the app store that was related to an in-app purchase:

•mt-last-in-app-purchase-response-code()

•mt-last-in-app-purchase-response-text()

•mt-last-in-app-purchase-response-was-user-canceled()

This enables you to make the next step in the workflow dependent on the success of the current step. For an example, see the actions of the The OnPurchaseUpdated Event in the Example Project. Note that these functions can be used to obtain the response of the app store to the last request made to it that was related to an in-app purchase.

An app store might respond with any of a number of responses, depending on which app store is involved. A code of 0 indicates a successful operation. The other codes indicate different types of failure. The function that returns response text would provide more information about the failure. One type of failure, however, should be handled differently since it is not an error. This would be when the end user cancels a purchase. To distinguish this type of purchase failure from errors, MobileTogether provides the function mt-last-in-app-purchase-response-was-user-canceled.

OnPurchaseUpdated: when an app store accepts a purchase request

When an app store accepts a purchase request, the purchase is automatically added to the In-App-Purchase Page Source. The purchase is said to be updated (in the page source) and the OnPurchaseUpdated event is triggered. A sequence of actions can be defined for the event, which enables you to seamlessly carry out actions, without requiring any user input, after a purchase request has been accepted. For example, you might want to acknowledge a purchase directly after it has been accepted (see next topic below). To access the event's Actions dialog, go to the project property In-App Purchase Actions.

Note the following points about the actions of the OnPurchaseUpdated event:

•While the actions of the OnPurchaseUpdated event are being processed, the $MT_UpdatedInAppPurchases variable is in scope. The variable contains a sequence of strings, which are the SKU_IDs of purchased products that have been updated in the In-App-Purchase Page Source. So, if one item has been purchased, then its SKU_ID can be obtained with the XPath expression $MT_UpdatedInAppPurchases[1]. The variable goes out of scope once the event's actions have been processed. This means that the variable can only be used in actions of the OnPurchaseUpdated event.

•In the In-App-Purchase Page Source, each Purchase element has a PurchaseState attribute that takes a value of either PENDING or PURCHASED. You might want to suitably modify your workflow to take this status into account.

For an example (i) of the kind of actions that can be defined for the OnPurchaseUpdated event, and (ii) of how to use the $MT_UpdatedInAppPurchases variable, see the description of this event in the example project: The OnPurchaseUpdated Event.

Activate product

Activate the purchased product in the app. After checking the purchase state, subscription validity, possible cancellation, etc, of the purchase, you will need to activate the product accordingly. This is a step that you as the designer of the app must carry out; MobileTogether cannot automatically do this for you.

Acknowledge Purchase

After the end user successfully buys a product via an in-app purchase, the app store accepts the request and sends information about the purchase to the app. On receiving this information, the purchase must be acknowledged from the app side, and this is something that you, as the app designer, must do silently without bringing the end user into the picture. The acknowledgment step enables the app to process the information received by the app store to determine whether the purchase is legitimate and whether to close the purchase from the vendor side. This provides you, as the app designer, with an opportunity to verify different aspects of the purchase. The app stores provide documentation that give you detailed information about what you should assess before acknowledging the purchase. Kindly read the relevant app store information before deciding on the steps to take before acknowledging. It is only after you acknowledge the purchase, that the app store will process the payment and route it to the product-owner's account.

Purchases are acknowledged via MobileTogether's Acknowledge Purchase action, and it is best to include this action as one of those to be carried out when the OnPurchaseUpdated event is triggered (see previous section above).

For details of this action, see the description of the Acknowledge Purchase action and the description of its implementation in the example project.

Query stores for purchase data

You can query the app store for all the purchases transacted by the current user. The action to do this is the Query Purchases action. When the action is executed, the app store returns data about the user's purchases, and key datapoints are stored in the Purchases element of the In-App-Purchase Page Source. Each purchase is stored in an individual Purchase element. You can then use this purchase data in the app's workflow. For detailed information, see the description of the Query Purchases action and the description of the Query Purchases button in the example project.

Restore purchases (iOS only)

The Apple Store keeps a record of all of an end user's purchases and enables the end user to restore all these purchases on an iOS device at any time. The Restore Purchases action can be used to query the Apple Store for all of an end user's purchases. The data returned is stored in the Purchases element of the In-App-Purchase Page Source, with each purchase being stored in an individual Purchase element. You can then use this purchase data in the app's workflow. For detailed information, see the description of the Restore Purchases action and the description of the Restore Purchases button in the example project.

Get/Report Consumables (Windows only)

After a consumable has been purchased, it can be consumed within the app. In the case of Windows apps, the Windows app store offers an option to keep a record of a user's current consumable balance. The Get/Report Consumable action addresses this Windows option. It can get the current balance from the Windows app store and report the fulfillment level of the consumable to the Windows app store. For details see the description of the action.

Keep track of the product's activation status

It is your responsibility to determine whether a product is active within the app at any given time. This decision would be based on the following factors:

•The product's PurchaseState as reported by the app store.

•In the case of consumable products, the current level of consumable credit. You will have to keep track of this in your app.

•In the case of subscriptions, the current state of the subscription relative to the start date and period of the subscription.

•Any other factor that affects the activation status of the product, such as a free extension period for a subscription.

REST interfaces

You can also use REST interfaces as far as these are supported on the respective platforms. The use of REST interfaces with AppStore Apps on Android has been tested, and the documentation of these interfaces is available here: https://developers.google.com/android-publisher/api-ref/rest.