ReadMe has been updated.

Android/WACNapiPaymentPlugin/README.md

@@ -2,11 +2,11 @@
 by WAC Application Services Ltd.
 
 ## Adding the Plugin to your project ##
-Using this plugin requires Android PhoneGap and the WAC PhoneGap Plugin Library. The WAC Library can be downloaded [here](https://www.wacapps.net/c/document_library/get_file?uuid=04e3aa8a-21e6-4a6a-976a-ff6b47fc1f88&groupId=155802).
+Using this plugin requires Android PhoneGap and the WAC PhoneGap Plugin Library. The WAC Library can be downloaded [here](http://www.wacapps.net/c/document_library/get_file?uuid=442d5263-e438-4f87-a723-4d6400256400&groupId=155802).
 
 1. Create your Android PhoneGap project. Details at http://phonegap.com/start/#android
 
-2. From WAC_PhoneGap_Plugin_Library, (a) move wacphonegap-1.0.jar and wac-1.0.jar into your project's libs directory and (b) add them to your build path. 
+2. From WAC_PhoneGap_Plugin_Library, (a) move wacphonegap-1.0.1.jar and wac-1.0.2.jar into your project's libs directory and (b) add them to your build path. 
 
 3. Copy the files in WACNapiPaymentPlugin/assets/www/ into your assets/www/ folder.
 
@@ -26,6 +26,10 @@ Using this plugin requires Android PhoneGap and the WAC PhoneGap Plugin Library.
 * Initial release
 * For API docs, see the assets/www/wac.js. For sample code, see assets/www/demo.js and assets/www/index.html.
 
+### 20120411 ###
+* New checkBillingAvailability() API has been added to check if Wac billing is available.
+* Bug fixes related to callback functions
+
 ## BUGS AND CONTRIBUTIONS ##
 
 Patches are welcome, send a pull request. Since this is not a part of PhoneGap Core (which requires a CLA), this should be easier.

Android/WACNapiPaymentPlugin/assets/www/demo.js

@@ -28,14 +28,29 @@ function onDeviceReady() {
 	NapiPayment.setDebugEnabled(isDebugEnabled);
 	NapiPayment.setEndPoint(endPoint);
 	NapiPayment.setSpoofIP(spoofIPStr);
-    NapiPayment.initializeNapi(appId, credential, secret, devname, redirectOAuthURI);
+    NapiPayment.initializeNapi(appId, credential, secret, devname, redirectOAuthURI, initializeNapiCallback);
 }
 
 /**
  * The Initialize Napi Callback
  */
 var initializeNapiCallback = function(r){
-	// do Nothing.
+	// Check the availability of the server.
+	//checkBillingAvailability can be used to find the availability of WAC billing services. (Optional)
+	NapiPayment.checkBillingAvailability(checkBillingAvailabilityCallback);
+}
+
+/**
+ * The callback method after checking the availability of the server.
+ */
+var checkBillingAvailabilityCallback = function(r){
+	hide('payment_option_loading');
+	show('WAC_payment_option');
+	if(!r.isBillingAvailable){
+		document.getElementById('WAC_payment').onclick = null;
+		show('billing_not_available');
+	}
+
 }
 
 /**
@@ -47,7 +62,7 @@ function startPayment() {
     hide('product_list');
     show('show_loading');
     // Get the list of all the operators.
-	NapiPayment.productList();
+	NapiPayment.productList(productListCallback);
     return false;
 }
 
@@ -69,36 +84,20 @@ var productListCallback = function(r) {
 };
 
 /**
- * The method starts the charge payment or the reserve payment process. The developer can select any of the options -
- * 1) NapiPayment.chargePayment or
- * 2) NapiPayment.reservePayment
+ * The method starts the reserve payment process.
  */
-function chargePayment(){
+function reservePayment(){
 	show('show_loading');
 	show('product_list');
 	hide('payment_options');
 	// Get the selected product from the drop down.
    	var selObj = document.getElementById('productList');
 	var itemId = selObj.options[selObj.selectedIndex].value;
-	//Do the payment. Choose any one of the two Payment methods below.
-	//NapiPayment.chargePayment(itemId);
-	NapiPayment.reservePayment(itemId);
+	//Reserve the payment.
+	NapiPayment.reservePayment(itemId, reservePaymentCallback);
 	hide('show_loading');
 }
 
-/**
- * The Charge Payment Callback
- */
-var chargePaymentCallback = function(r){
-	if(r.key != undefined && r.key != ''){
-		if(r.key == 'transactionDetails'){
-			showSuccessTransaction(r);
-		}
-	} else if(r.error != undefined && r.error != ''){
-		showFailedTransaction(r);
-	}
-}
-
 /**
  * The Reserve Payment Callback
  */
@@ -110,7 +109,7 @@ var reservePaymentCallback = function(r){
 			hide('show_loading');
 			show('file_downloading');
 
-			NapiPayment.capturePayment(r.value);
+			NapiPayment.capturePayment(r.value, capturePaymentCallback);
 		}
 	} else if(r.error != undefined && r.error != ''){
 		showFailedTransaction(r);
@@ -122,11 +121,17 @@ var reservePaymentCallback = function(r){
  */
 var capturePaymentCallback = function(r){
 	hide('file_downloading');
-	chargePaymentCallback(r);
+	if(r.key != undefined && r.key != ''){
+		if(r.key == 'transactionDetails'){
+			showSuccessTransaction(r);
+		}
+	} else if(r.error != undefined && r.error != ''){
+		showFailedTransaction(r);
+	}
 }
 
 /**
- * PhoneGap asynchronous call callback for chargePayment
+ * PhoneGap asynchronous call callback for capturePayment
  */
 var showSuccessTransaction = function(r) {
 	hide('show_loading');
@@ -220,7 +225,7 @@ var noProductsFound = '<tr><td colspan = "2">No Products found</td></tr>';
  */
 function transactionList(){
 	expandCollapablePanel();
-	NapiPayment.transactionList();
+	NapiPayment.transactionList(transactionListCallback);
 }
 
 /**
@@ -301,7 +306,7 @@ function checkTransaction(name, currency, amount, serverRef, itemId){
 	document.getElementById('check_transaction_item_id').innerHTML = itemId;
 	document.getElementById('check_transaction_btn').onclick = function (){
 		var args=[];
-		NapiPayment.checkTransaction(serverRef,itemId);
+		NapiPayment.checkTransaction(serverRef,itemId, checkTransactionCallback);
 	};
 }
 

Android/WACNapiPaymentPlugin/assets/www/wac.js

@@ -74,17 +74,21 @@ var NapiPayment = {
 		 * information). This data is obtained when the application is
 		 * registered with WAC.
 		 * 
-		 * The results of the call can be captured in a callback function initializeNapiCallback with parameters as a json object <code>r</code>. 
+		 * The results of the call can be captured in a callback function named callback being passed as one of the parameters. 
+		 * The callback function should have one parameter which is supposed to be a json object and it holds the result of initializeNapi call.
+		 * In this version of plugin the callback json object is null.
+		 * 
 		 * Implement the callback object as below.
 		 * <code>
 		 * var initializeNapiCallback = function(r){
 		 *     // do your stuff here.
 		 * }
 		 * </code>
 		 * 
-		 * In this version of plugin the callback json object r is null.
+		 * and pass the callback object as in NapiPayment.initializeNapi(appId, credential, secret, devname, redirectOAuthURI, initializeNapiCallback);
+		 * 
 		 */ 
-        initializeNapi : function(appId, credential, secret, devname, redirectOAuthURI) {
+        initializeNapi : function(appId, credential, secret, devname, redirectOAuthURI, callback) {
         	if(isEmpty(appId)){
         		alert('Application Id is null. Cannot initialize Napi.');
         		return;
@@ -106,7 +110,7 @@ var NapiPayment = {
         		return;
         	}
         	var args = {"appId": appId, "credential": credential, "secret": secret, "devname": devname, "redirectOAuthURI": redirectOAuthURI};
-            return window.plugins.Napi.invoke('initializeNapi', args, initializeNapiCallback);
+            return window.plugins.Napi.invoke('initializeNapi', args, callback);
         },
 
         /**
@@ -129,32 +133,75 @@ var NapiPayment = {
         setEndPoint : function(endPointStr) {
             return window.plugins.Napi.invoke('setEndPoint', endPointStr, null);
         },
+
+        /**
+		 * The method checks whether the server is available for payments or not. 
+		 * The results of the call can be captured in a callback function named callback being passed as one of the parameters. 
+		 * The callback function should have one parameter which is supposed to be a json object and it holds the result of checkBillingAvailability call.
+		 * 
+		 * Implement the callback object as below.
+		 * <code>
+		 * var checkBillingAvailabilityCallback = function(r){
+		 *     // do your stuff here.
+		 * }
+		 * </code>
+		 * 
+		 * and pass the callback object as in NapiPayment.checkBillingAvailability(checkBillingAvailabilityCallback);
+		 * 
+		 * Limitations of this method: At the point of calling this method WAC have not yet checked the individual user. In the case the user is out-of-band (e.g. WiFi), we have not yet identified the operator either because we want to avoid having to ask the user for their phone number when this method is called. This means that this method behaves as follows:
+         * 		- In-band flow, app not LIVE or not published to this operator: will return "false"
+         * 		- Out-of-band flow, app not LIVE or not published in the country of the access point IP address: will return "false"
+         * 		- Out-of-band flow, app published in the country of the access point IP address but not the operator of the user: will return "true"
+         * 		- Individual user can't use WAC even if other users of this operator can, e.g. user blacklisted, user doesn't have enough credit etc.: will return "false"
+         * 		- App is LIVE, published to this operator and individual user can use WAC: will return "true"
+		 */ 
+        checkBillingAvailability : function(callback) {
+            return window.plugins.Napi.invoke('checkBillingAvailability', null, callback);
+        },
 
         /**
 		 * Fetches the list of product items for the current application 
+		 * The results of the call can be captured in a callback function named callback being passed as one of the parameters. 
+		 * The callback function should have one parameter which is supposed to be a json object and it holds the result of productList call.
+		 * 
+		 * Implement the callback object as below.
+		 * <code>
+		 * var productListCallback = function(r){
+		 *     // do your stuff here.
+		 * }
+		 * </code>
+		 * 
+		 * and pass the callback object as in NapiPayment.productList(productListCallback);
 		 */ 
-        productList : function() {
-            return window.plugins.Napi.invoke('productList', null, productListCallback);
+        productList : function(callback) {
+            return window.plugins.Napi.invoke('productList', null, callback);
         },
 
 		/**
-		 * The function can be called to do an Express payment. The function takes Item Id selected by the user to do the charge payment.
-		 * The results of the call can be captured in a callback function chargePaymentCallback with parameters as a json object <code>r</code>. 
+		 * Deprecated function. The function can be called to do an Express payment. The function takes Item Id selected by the user to do the charge payment.
+		 * The results of the call can be captured in a callback function named callback being passed as one of the parameters. 
+		 * The callback function should have one parameter which is supposed to be a json object and it holds the result of chargePayment call.
+		 * 
 		 * Implement the callback object as below.
 		 * <code>
 		 * var chargePaymentCallback = function(r){
 		 *     // do your stuff here.
 		 * }
 		 * </code>
+		 * 
+		 * and pass the callback object as in NapiPayment.chargePayment(itemId, chargePaymentCallback);
+		 * 
 		 */
-        chargePayment : function(itemId) {
-            return window.plugins.Napi.invoke('chargePayment', itemId, chargePaymentCallback);
+        chargePayment : function(itemId, callback) {
+            return window.plugins.Napi.invoke('chargePayment', itemId, callback);
         },
 
 		/**
          * Reserves the Payment. The payment is held until the capturePayment is made. The function takes Item Id selected by the user to do the reserve payment.
          * This gives the option to pause the payment until the content is delivered to the user.
-         * The results of the call can be captured in a callback function reservePaymentCallback with parameters as a json object <code>r</code>. 
+         * The results of the call can be captured in a callback function named callback being passed as one of the parameters. 
+		 * The callback function should have one parameter which is supposed to be a json object and it holds the result of reservePayment call.
+		 * 
 		 * Implement the callback object as below.
 		 * <code>
 		 * var reservePaymentCallback = function(r){
@@ -163,54 +210,71 @@ var NapiPayment = {
 		 *     NapiPayment.capturePayment(r.value);
 		 * }
 		 * </code>
+		 * 
+		 * and pass the callback object as in NapiPayment.reservePayment(itemId, reservePaymentCallback);
          * 
          */
-        reservePayment : function(itemId) {
-            return window.plugins.Napi.invoke('reservePayment', itemId, reservePaymentCallback);
+        reservePayment : function(itemId, callback) {
+            return window.plugins.Napi.invoke('reservePayment', itemId, callback);
         },
 
 		/**
          * Captures or makes a Payment after reserving a transaction. This function takes reserved transaction data as a parameter for making the payment. 
-         * The results of the call can be captured in a callback function capturePaymentCallback with parameters as a json object <code>r</code>. 
+         * The results of the call can be captured in a callback function named callback being passed as one of the parameters. 
+		 * The callback function should have one parameter which is supposed to be a json object and it holds the result of capturePayment call.
+		 * 
 		 * Implement the callback object as below.
 		 * <code>
 		 * var capturePaymentCallback = function(r){
 		 *     // do your stuff here.
 		 * }
 		 * </code>
+		 * 
+		 * and pass the callback object as in NapiPayment.capturePayment(reserveObj, capturePaymentCallback);
+		 * 
          */
-        capturePayment : function(reservedTransactionObj) {
-            return window.plugins.Napi.invoke('capturePayment', reservedTransactionObj, capturePaymentCallback);
+        capturePayment : function(reservedTransactionObj, callback) {
+            return window.plugins.Napi.invoke('capturePayment', reservedTransactionObj, callback);
         },
 
 		/**
          * List the transaction details for a user.
-         * The results of the call can be captured in a callback function transactionListCallback with parameters as a json object <code>r</code>. 
+         * The results of the call can be captured in a callback function named callback being passed as one of the parameters. 
+		 * The callback function should have one parameter which is supposed to be a json object and it holds the result of transactionList call.
+		 * 
 		 * Implement the callback object as below.
 		 * <code>
 		 * var transactionListCallback = function(r){
 		 *     // do your stuff here.
 		 * }
 		 * </code>
+		 * 
+		 * and pass the callback object as in NapiPayment.transactionList(transactionListCallback);
+		 * 
          */
-        transactionList : function() {
-            return window.plugins.Napi.invoke('transactionList', null, transactionListCallback);
+        transactionList : function(callback) {
+            return window.plugins.Napi.invoke('transactionList', null, callback);
         },
 
 		/**
          * Provides the transaction details for a given transaction ID. The method takes two arguments. 
          * The first one is the server reference code of the item selected and the second one is the item Id.
-         * The results of the call can be captured in a callback function checkTransactionCallback with parameters as a json object <code>r</code>. 
+         * The results of the call can be captured in a callback function named callback being passed as one of the parameters. 
+		 * The callback function should have one parameter which is supposed to be a json object and it holds the result of checkTransaction call.
+		 * 
 		 * Implement the callback object as below.
 		 * <code>
 		 * var checkTransactionCallback = function(r){
 		 *     // do your stuff here.
 		 * }
 		 * </code>
+		 * 
+		 * and pass the callback object as in NapiPayment.checkTransaction(serverRef,itemId, checkTransactionCallback);
+		 * 
          */
-        checkTransaction : function(serverReferenceCode, itemId) {
+        checkTransaction : function(serverReferenceCode, itemId, callback) {
         	var args = {"serverReferenceCode": serverReferenceCode, "itemId": itemId};
-            return window.plugins.Napi.invoke('checkTransaction', args, checkTransactionCallback);
+            return window.plugins.Napi.invoke('checkTransaction', args, callback);
         }
 };