Managing a subscription

You can use the following functions in the Payment Service for BlackBerry WebWorks to manage subscriptions in your app.

Subscriptions can be referred to as app-level subscriptions or digital goods-level subscriptions. When you add your app to BlackBerry World you can select Subscription as the license type for your app. If you add a digital good to your app, you can select Subscription as the license type for your in-app digital good.

Checking an app-level subscription

When a user tries to access an app-level subscription, the Payment Service calls blackberry.payment.checkAppSubscription to verify that the user has rights to the subscription.

If the transaction is successful and the user's BlackBerry ID matches a currently active subscription to the app, the Payment Service returns the onSuccess function with the parameter data.subscriptionExists set to True. If no match is made, then data.subscriptionExists is set to False.

If the transaction is not successfully completed, the Payment Service returns the onFailure function with a PaymentError object.
<script type="text/javascript">
 function checkAppSubscription() {
     try {
         blackberry.payment.checkAppSubscription(onSuccess, onFailure);
     } catch (e){
         alert("Error" + e);
     }
 }

 function onSuccess(data) {
     alert("User is " + (data.subscriptionExists ? "" : "not ") + "subscribed to the app.");
 }

 function onFailure(error) {
     alert("Error occurred: " + error.errorText + ", " + error.errorID);
 }
</script>

Checking a digital goods subscription

When a user tries to access a digital goods subscription, the Payment Service calls blackberry.payment.checkExisting to verify that the user has rights to the subscription. The function includes information to describe the digital good: id for the identifier assigned by BlackBerry World or sku for the SKU of the digital good. If both arguments are included in the transaction, id takes precedence and sku is ignored.

If the BlackBerry ID associated with the transaction is subscribed to the digital good, the Payment Service returns the onSuccess function with the parameter data.subscriptionExists set to True. If the transaction is successful, but no match is made, then data.subscriptionExists is set to False.

If the transaction is not successfully completed, the Payment Service returns the onFailure function with a PaymentError object.
<script type="text/javascript">
  function checkSubscription() {
      try {
          blackberry.payment.checkExisting({
              "id": 12345"
          }, onSuccess, onFailure);
      } catch (e) {
          alert ("Error" + e);
      }
  }

 function onSuccess(data) {
     alert("User is " + (data.subscriptionExists ? "" : "not ") + "subscribed to the item.");
 }

 function onFailure(error) {
     alert("Error occurred: " + error.errorText + ", " + error.errorID);
 }
</script>

Canceling a subscription

A user can only cancel a subscription for a digital good; cancellation of other types of purchases (license types) are not supported. A purchase ID is required in order to identify the subscription that a user wants to cancel, so when a user makes a request to cancel a subscription, your app calls a getExistingPurchases function first. A successful getExistingPurchases function returns the purchase ID so that the cancellation can be completed.

If the blackberry.payment.cancelSubscription function is successful, the onSuccess function returns data.subscriptionCancelled: True.

If a user successfully cancels a subscription, the subscription remains valid until the end of the current subscription period. For example, if the user has paid for a subscription to December 31st, and cancels the subscription on December 15th, the subscription remains valid until the paid period expires on December 31st.

If the blackberry.payment.cancelSubscription function is not successful, the onFailure function returns a PaymentError object.

function cancelSub() {
    try {
        blackberry.payment.cancelSubscription("18722506", onCancelSubSuccess, onCancelSubError);
    } catch (e) {
        alert("cancelSubscription exception");
        console.log(e);
    }
}

function onCancelSubSuccess(data) {
    console.log(data);
    alert("Cancellation " + (data.subscriptionCancelled ? "" : "NOT ") + "successful");    
}

function onCancelSubError(error) {
    console.log(error);
    alert("Error occurred: " + error.errorText + ", " + error.errorID);

Last modified: 2014-10-09



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus