COPYRIGHT 2012 DROIDLA LIMITED

Transcription

1 Integrating with your Website COPYRIGHT 2012 DROIDLA LIMITED ALL RIGHTS RESERVED DROIDLA LIMITED v1.0 - NOVEMBER 2012

2 Contents OVERVIEW OF THE INTEGRATION PROCESS CREATE AN ACCOUNT ACCEPT TERMS & CONDITIONS CREATE A SITE CREATE RESTFUL SERVICE DEPLOY JAVASCRIPT CUSTOMIZE LOGIN & PAYMENT FIELDS START USING ZAPPER TECHNOLOGIES

3 ZAPPER TECHNOLOGIES Integrating with your Website Overview of the Integration Process Integrating Zapper Technologies with your website(s) is really easy. Before we get into the detail here is a quick overview of the process: Create a merchant account with Zapper Technologies Accept the Terms & Conditions for using Zapper Technologies Create the details of the site and the data fields you want sent by the user s device Create a RESTful service to process the data that will be sent by Zapper Technologies Deploy the supplied Zapper Technologies Javascript files into your site. Customize your login and payment fields to the names required by Zapper Technologies Start using Zapper Technologies 1. Create an Account Register a merchant account on the web-site. 2

4 2. Accept Terms & Conditions Complete your business details, and Accept the merchant s' Terms & Conditions for using Zapper Technologies. 3

5 3. Create a Site Create a site per the below steps: Choose the relevant data fields required from users, for registration and payments on your website. 4

6 4. Create RESTful Service Once your site is created, you need to create a web service to which Zapper Technologies can send the required data. Zapper Technologies makes use of RESTful services (REpresentational State Transfer-compliant web services) to make the process as easy as possible. RESTful services are simply services on a web server that answer structured requests in a structured way. In implementing these services JSON (JavaScript Object Notation) is used as a way to structure both the request and the response. If you are unfamiliar with REST in general, please refer to for some valuable background information that you will need to implement the services required by Zapper Technologies. Your RESTful service needs to expose the required methods on the site URL that you created. Your service needs to provide two methods, one that accepts an HTTP GET request and another that accepts an HTTP POST request. In the GET request a string will be passed to your method and you need to return a JSON string. The POST request needs to accept JSON and return JSON. The POST request implementation follows below and needs to accept different JSON packets depending on the Task being processed. The GET method simply accepts a SessionId as a string and returns a JSON packet. This method is described later in the document. Registration When a user scans the QR Code on your website for the first time a JSON packet will be sent to your RESTful service (POST) containing the following data: Registration Request Property Name Type Description Required SessionId String This is a unique identifier supplied by the merchant via the QR Code Yes 5

7 Data String JSON packet representing the information required. Password String This is the users password to login to the merchant website TaskId Int This indicates registration (0), login (2), purchase (1) or navigation (3). This is used to determine what response is required. Yes Optional No You identify the packet as a registration packet by the presence of the Password property and TaskId = 0. If the Password property is absent and TaskId = 2 then it is a Login packet. The Data property contains an array of all the information for the fields that you specified in the merchant page: Property Name Type Description Required Answers Array of Answer The answer list used to complete a purchase form or registration process. Yes TABLE - DATA PROPERTIES Answer Properties Property Name Type Description Required QuestionId Integer Yes QuestionGroupId Integer Yes AnswerValue String Optional Table - Answer properties An example of the JSON sent is: TABLE - ANSWER PROPERTIES "Password":"Nj32J6hg", "Data": "Answers":[ "AnswerValue":"appleby@gmail.com", "QuestionGroupId":1, "QuestionId":1, "AnswerValue":"john", "QuestionGroupId":1, "QuestionId":2, 6

8 ,,, "AnswerValue":"appleby", "QuestionGroupId":1, "QuestionId":3 "AnswerValue":"1", "QuestionGroupId":1, "QuestionId":4 "AnswerValue":"john", "QuestionGroupId":1, "QuestionId":5 "AnswerValue":"john.appleby", "QuestionGroupId":1, "QuestionId":6 ], "SessionId":"9ecab749-5df0-affa", "Taskid":0 You need to process any business logic required on your side to register the user on your website and then return a response back to the Scanner. Registration Response The Scanner expects the registration response to contain the following properties as part of the JSON packet: Property Name Type Description Required IsSuccess Boolean Indicates if the operation was successful. n/a ErrorMessage String If the operation failed then an error message must be returned. n/a Username String The username that the user was registered with. n/a Example Response: "IsSuccess":true, "ErrorMessage":null, "Username":" appleby@gmail.com " Once a user is registered on your site, all subsequent scans by that user will call the Login functionality. 7

9 Login Login Request The packet is exactly the same as the Registration packet except for the Data property and no Password property. Property Name Type Description Required SessionId String This is a unique identifier supplied by the merchant via the QR Code Data String JSON packet representing the information required. TaskId Int This indicates registration (0), login (2), purchase (1) or navigation (3). This is used to determine what response is required. Yes Yes No The Data Property will contain an encrypted key to allow the Scanner and your website to communicate securely. The SessionId and the value in the Data field must be stored by your service in a database or another system as the Javascript on your Login Page will make a call to your service (GET) passing the SessionId and expecting thesessionid and Data properties to be returned. Sample Login Request JSON packet "SessionId": f3180c d4b, "Data": U2FsdGVkX1/sJ1W1kore2RsvljArcrtwnGeMVpeaW/i96lfjAfx5GB5FH5, "TaskId":2 Login Response Sample Login Response JSON packet "IsSuccess":True, "ErrorMessage":null, A merchant may add navigation options to the login response this will allow the user to navigate to a specific page after logging in to the website. Example response: "IsSuccess":true, "ErrorMessage":null, "NavigationOptions":[ "Text": Shop, Value : "Text": Account, Value : ] 8

10 The Navigation options will appear on the device and the user will tap the option and will be taken there on the website. HTTP GET The HTTP GET operation is used to invoke the Session lookup function. The SessionId is required to be supplied as a GET parameter. This is used to uniquely identify the session. The Javascript in your Login/Payments pages will pass the unique SessionId string to this method. You will need to lookup the Data Property for this SessionId that you stored when processing the Login call and return it. Typically, the user would access the service URL as where the 05bf9c21-faf7-041f is the requested Session Id. The response for the HTTP GET operation must be as follows: Property Name Type Description Required IsSuccess Boolean Indicates if the operation was successful. n/a ErrorMessage String If the operation failed then an error message must be returned. SessionId String This is a unique identifier supplied by the merchant via the QR Code n/a Yes 9

11 Data String JSON packet representing the information required. This is the same property that you stored when processing the Login call. Yes Example response: "IsSuccess": true, "ErrorMessage": null, "SessionId": "05bf9c21-faf7-041f", "Data": "U2FsdGVkX1/nr+l3tMyQ33QrxyrBtrZY4olDODSIcBU1O Yhd42SiOkmXWDxK5DbE dpxjzikxq1i9ooma0p5mjh9pqwh7n6gtrrwyjg8eb Jkc707h38QjN8K4GhPNzVPF " 10

12 5. Deploy Javascript Login Page Once all of the services are implemented you need to get your Login/Registration page working with Zapper Technologies. The following Javascript Libraries must be added to the page: JQuery Libraries available from Zappertech-1.0.js (Download link) Qrcode.js (Download link) Aes.js (Download link) <script src="scripts/jquery js"></script> <script src="scripts/aes.js" type="text/javascript"></script> <script src="scripts/qrcode.js"></script> <script src="scripts/zappertech-1.0.js"></script> 11

13 6. Customize Login & Payment Fields On your login page create two hidden fields called MerchantId and SiteId and set their values to be the MerchantId and SiteId you received from the Zapper Technologies site. <input id="merchantid" type="hidden" value="2" /> <input id="siteid" type="hidden" value="3" /> Create a div called ZapperQrCode and position it where you want the QR Code to display. <div id="zapperqrcode"> </div> Lastly you need to invoke the Zapper Technologies function to allow the data to be retrieved and responses polled. <script type="text/javascript"> $(document).ready(function () zapper_setup(0) ) </script> An example of a page once completed could be: 12

14 The following is a sample html login page: <html xmlns=" <head runat="server"> <title></title> <script src="scripts/jquery js" type="text/javascript"></script> <script src="scripts/qrcode.js" type="text/javascript"></script> <script src="scripts/zappertech-1.0.js" type="text/javascript"></script> <script src="scripts/aes.js" type="text/javascript"></script> <script type="text/javascript"> $(document).ready(function () zapper_setup(0) ) </script> <style type="text/css"> #ZapperQrCode width: 241px;.style1 width: 100px; </style> </head> <body> <form id="form1" runat="server"> <div> <input id="merchantid" type="hidden" value="2" /> <input id="siteid" type="hidden" value="3" /> </div> <div id="zapperqrcode"> </div> </form> <table style="width:100%;"> <tr> <td class="style1"> <strong>login</strong> </td> <td> <input id=" " type="text" /></td> </tr> <tr> <td class="style1"> <strong>password</strong></td> <td> <input id="password" type="text" /></td> </tr> <tr> <td class="style1"> </td> <td> <input id="login" type="submit" value="submit" /></td> </tr> </table> </body> </html> 13

15 Map HTML Fields to Returned Data The ZapperTech JavaScript library assumes that the username div s Id is Username, similarly the password is Password and the login button Login. If the div s have different names, you will have to either rename the div s, or update the JavaScript. If you decide to update the JavaScript, you need to amend the fields that are being looked for in the Zappertech1-0.js file As an example: g_ div = $('# '); Replace # with #<new name> function zapper_setup(actionid) g_ div = $('# '); g_passworddiv = $('#Password'); g_loginbutton = $('#LoginButton'); g_purchasebutton = $('#PurchaseButton'); g_usersessionid = generatesessionguid(); g_userencryptionkey = generatesessionguid(); g_merchantid = $("#MerchantId").val(); g_siteid = $("#SiteId").val(); g_qrcodetext = g_qrbaseurl + actionid + ":" + g_merchantid + ":" + g_siteid + ":" + g_usersessionid + ":" + g_userencryptionkey; update_qrcode(); if (0 == actionid) polllogindata(); else if (1 == actionid) pollpurchasedata(); Checkout Page Implementing Zapper Technologies on your checkout page allows a user to populate all the required fields by scanning a QR code. The process is exactly the same as how you implemented the Login/Registration calls. The same methods are used, all that changes is that the Purchase (1) value is sent to the POST method. The Javascript call on the completion of page load now takes a taskid of 1. <script src="scripts/jquery js"></script> <script src="scripts/qrcode.js"></script> <script src="scripts/aes.js"></script> <script src="scripts/zappertech-1.0.js"></script> <script type="text/javascript"> $(document).ready(function () zapper_setup(1) ) </script> If the user is not registered then the Scanner client will present the user with a form containing a list of questions for the user to complete. The Scanner will call your POST method with a registration call. The ZapperTech JavaScript library assumes that the div s have specific names. The Field names being looked for are described in the following method from the Zappertech1-0.js file: 14

16 function getpurchasedivname(groupid, questionid) if (groupid == qg_personal) if (questionid == q_ ) return $("# "); if (questionid == q_firstname) return $("#FirstName"); if (questionid == q_lastname) return $("#LastName"); if (questionid == q_title) return $("#Title"); if (questionid == q_name) return $("#Name"); if (questionid == q_preferredusername) return $("#PreferredUsername"); if (questionid == q_password) return $("#Password"); if (questionid == q_phonenumber) return $("#HomePhone"); if (questionid == q_gender) return $("#Gender"); if (questionid == q_dateofbirth) return $("#DateOfBirth"); if (questionid == q_website) return $("#Website"); else if (groupid == qg_address) if (questionid == q_addressline1) return $("#Address1"); if (questionid == q_addressline2) return $("#Address2"); if (questionid == q_town_city) return $("#City"); if (questionid == q_country) return $("#Countries"); if (questionid == q_postcode_zip) return $("#"); if (questionid == q_county) return $("#"); else if (groupid == qg_billingaddress) if (questionid == q_addressline1) return $("#Address1"); if (questionid == q_addressline2) return $("#Address2"); if (questionid == q_town_city) return $("#City"); if (questionid == q_country) return $("#Countries"); if (questionid == q_postcode_zip) return $("#"); if (questionid == q_county) return $("#"); else if (groupid == qg_shippingaddress) if (questionid == q_addressline1) return $("#Address1"); if (questionid == q_addressline2) return $("#Address2"); if (questionid == q_town_city) return $("#City"); if (questionid == q_country) return $("#Countries"); if (questionid == q_postcode_zip) return $("#"); if (questionid == q_county) return $("#"); else if (groupid == qg_card) if (questionid == q_cardnumber) return $("#CardNumber"); if (questionid == q_cardname) return $("#CardHolderName"); if (questionid == q_cardtype) return $("#CardTypes"); if (questionid == q_cardissuenumber) return $("#IssueNo"); if (questionid == q_cardstartdatemonth) return $("#StartMonths"); if (questionid == q_cardstartdateyear) return $("#StartYears"); if (questionid == q_cardexpirydatemonth) return $("#ExpiryMonths"); if (questionid == q_cardexpirydateyear) return $("#ExpiryYears"); if (questionid == q_cardcvc) return $("#CVC"); else if (groupid == qg_terms) ; 7. Start Using Zapper Technologies Start using Zapper Technologies and allow your website users to benefit from the simple and easy Registration, Login and Payment Processes now available on your website. 15