How to connect to 3rd party API, on the example of credit card payment via Autorize.net API by Wells Fargo

This tutorial shows how to create credit card form, connected to 3rd party provider API – in this case to Wells Fargo’s Authorize.Net API. The tutorial provides only one usecase – sending credit card details – but using it as a guideline, you should be able to figure out how to connect to all Authorize.Net methods.

You will need Embedded API Adapter for this.

1. Set up an account with Authorize.Net and log in.

2. Go to “Settings” > “Keys and API” and obtain two keys there: API Login ID and Transaction Key. You might need to generate the last one.

2. Then, visit the website: /developer.authorize.net/api/reference/index.html

3. First – note two pieces of information:
HTTP Request Method: POST
Sandbox API Endpoint: /apitest.authorize.net/xml/v1/request.api

4. Scroll a bit down to “Test Your Authentication Credentials” and insert your API Login ID and Transaction Key into the form, then click . Once they are accepted, they will be populated into all example API calls on this sandbox website.

5. Scroll further down to “Charge a Credit Card” section. This tutorial will only show how to process payment through API. Other API calls can be done in similar way. Click TRY IT and JSON tabs. Copy entire JSON. You’ll need it in a minute in Kinetise.

6. Go back to Kinetise. Add (drag&drop) FORM widget to phone screen. We will deal with API-call settings in a moment, right now let’s focus on creating the form.

7. By default FORM widget comes with a TEXTINPUT subwidget (plus “Submit” button). Left-click on it, to open its properties panel on the right.

8. You can modify some properties here, especially:

  • formID – this would work as a name of a variable created within the application and used further to be passed to API. Let’s name it “cardnumber” for clarity.
  • keyboard type – credit card consists of digits only, so let’s give user digits-only keyboard.
  • watermark – can be used as instructions for the user
  • validation rules – credit card number is 16-digits long number, consisting of digits only, so this can be defined as a ReGeX.

7. Add more TEXTINPUT fields to this FORM – at least three for card expiration year, month, as well as CVC code. FormID of each of those fields has to be unique, ideally name them: “cardnumber”, “year”, “month”, “cvc” . If you want to put some of TEXTINPUTS next to each other, use Horizontal Container and put them in it. At the end, enter some dummy data into the form, but do not press Send button. Your credit card form should look like this:

8. Now the tricky part – connecting to API. Switch to Properties panel of the whole FORM widget. Make it send data to RESTfulAPI and click on the cog icon to open Request Settings popup.

9. Make sure the API call will be made via POST method and paste that Sandbox URL from Authorize.net. Next, switch to BODY tab.

10. This is where you’ll need Embedded API Adapter. Kinetise apps send data in a default structure – JSON, as in “Original Request Body“. It is defined in /helpcenter.kinetise.com. If you are able to adjust your backend API to Kinetise default data structure, then you don’t need Embedded API Adapter at all. But if the API you want to connect to is an established one, and you are not able to adjust it – you will need Embedded API Adapter, which modifies the structure of sent data.

11. Authorize.Net API expects to receive a JSON as in the example you have copied from Authorize.Net sandbox website. Paste this JSON now into “Request Body Transform” field. This will be the JSON your mobile app actually sends to Authorize.Net API. Test it now by pressing TEST button – you will see the response confirming data was received.

12. However, pasted JSON had all the credit card data hardcoded and we need them dynamic – as mobile app user has entered them in the form. We’ll need to modify that parsed JSON a bit. Find “cardNumber” in it and replace its hardcoded value of “5424000000000015” with dynamic .form.cardnumber. Do the same for the other data fields. Ultimately you should replace this part of the JSON:

“creditCard”: {
“cardNumber”: “5424000000000015”,
“expirationDate”: “2020-12”,
“cardCode”: “999”
}

with this one:

“creditCard”: {
“cardNumber”: .form.cardnumber,
“expirationDate”: (.form.year + “-” + .form.month),
“cardCode”: .form.cvc
}

13. That’s all, your work is done and you can compile the app. You could also collect more data in the form and pass them to API in the same way. Or use data stored in Local Variables of the application, such as user name and surname. In this case you’d need to first pass them to the FORM, by selecting LocalVariable from “dynamic params” dropdown under BODY tab and then using them in JSON as .params.variablename. How to create LocalVariables to be used throughout the app – you can check here: /helpcenter.kinetise.com/editor-tutorials?tutorial-detail=how-to-inject-variables-to-mobile-app-from-backend or just make any FORM widget store data in Local Variables.

 

 

How to add “Forgot password” functionality

First of all, “Forgot password” functionality is a backend functionality. Mobile app can only send information, that user with XXX email address requested password reset. Let’s show you how to do that. We’ll use KinetiseCMS as a backend, because it has required logic and workflow already built it, but mobile app can do that with any backend you like.

Images will be added shortly, but text-only version should be enough to build it.

1. We’ll need a user on KinetiseCMS to perform this action. Open KinetiseCMS, go to USERS table and create one user.

2. Add email address to this user. Ideally – your email address, so you can test it easily. No need to press any OK button here, inline editing in KinetiseCMS get saved instantly on focus-out.

3. KinetiseCMS can be closed now, let’s get back to building the app.

4. Let’s add TEXT widget on the Splash Screen. First, make it say “Forgot password”. Then make it open a new overlay – set proper action in EVENTS tab of the TEXT widget.

5. Open the overlay and drag&drop FORM widget to it.

7. Make this FORM point to KinetiseCMS, USERS table and RESTORE PASSWORD endpoint.

8. Change FormID of the default TEXTINPUT field to “email”.

9. That’s it, try it out. Type in your email into the FORM and submit it. Check your email and follow instructions to change the password. Later you can add LOGIN widget to verify if resetting password worked.

How to add a map with a search bar?

This tutorial explains how to add a map with searchable pins. The app needs backend for it and it can be any backend exposing properly prepared RESTful API. However, this tutorial explains how to build this functionality using KinetiseCMS, because it has Search functionality already built-in in its logic and API. Therefore we can build it in 30 seconds.

    1. Drag&drop MAP widget.

    1. Set its source to Online and to “From Kinetise CMS”.

    1. Drag&drop SEARCH widget, you can place it above the map or anywhere else on the phone screen.

    1. Click to configure where search results should be displayed.
    2. From first dropdown select current screen, from second dropdown select the map widget.

    1. Click . Don’t bother with Http Request Parameter – it will be automatically added to MAP widget API call made to Kinetise CMS.
    2. That’s it, try to test the functionality. Assuming you are using default default KinetiseCMS data, you should see 4 blue pins on the map. Type “data” in search box and press Enter on your laptop keyboard – Map widget passes “data” search query to KinetiseCMS and it gets only 3 pins to display, because description of one of the initial 4 did not contain the word “data”.
      1. To get better understanding how this was handled, click on MAP widget, to open its Properties panel on the right and click cog icon to the right of “sample” table dropdown selection.
        In REQUEST SETTINGS popup, you can see that “_search” parameter has been added to Http request. Search widget stored it as a Local Value. KinetiseCMS has search functionality built-in: it responds with those records, which contain search query. This functionality and many other KinetiseCMS built-in features have been explained in CMS spec.

(213) 739-6126

GPS Tracking is a powerful feature. It periodically sends users GPS-coordinates to  the backend. Such feature is a foundation for a range of popular logistics apps – Uber for example.

How to launch it

Actions “Start GPS tracking” and “Stop GPS tracking” can be attached to any TEXT or IMAGE widget – just select it in EVENTS tab.
Every X seconds (Interval parameter) it makes API-call to a specified URL, provided that the position has changed by at least Y meters (Minimum Distance) since this API-call was invoked last time.

So for example, in case the Minimum Distance is set to 100 meters and user has moved by only 50 meters, the API-call will not be invoked.

Prior to each API-call, device’s GPS is asked for the most recent GPS coordinates. Which are then passed with the API-call to the backend server.

User needs to have GPS working in his smartphone and given approval to use it by the app.

“Stop GPS Tracking” simply stops making API-calls. It does not send “Stop” information via any API-call.

How to initiate values in FORM fields and TOGGLE

This is a bit tricky. As you might have noticed, each subwidget for the FORM widget (i.e. TextInput, Dropdown, Checkbox), can have “Init Value”. You can retrieve it from the backend by switching this “Init Value” to “Dynamic” mode… if it wasn’t disabled.

To enable it, whole FORM must be put inside another widget, which retrieves data from the backend, which is – LIST widget. So:

  1. Add LIST widget
  2. Add FORM widget into first item of the LIST widget
  3. You may delete all other widgets from that first item of the LIST
  4. And reduce items count to 1 and disable Show More in the LIST

So, the screen structure should look like this:

Now if you check that TextInput, you’ll see that “Dynamic” mode for Init Value is enabled. And you can select which node from the feed (connected in LIST widget) should be the init value.

The same refers to TOGGLE, even if it is used without FORM widget. Please note it expects “0” value to initiate TOGGLE in disabled state and “1” for enabled.

Build native mobile chatbot app connected to Watson Conversation

Briefly about the architecture here:

The app will include only one screen – a chat thread. Together with a form containing textinput field to enter user inputs.

Conversation history will be collected in Local Database (on mobile device), and displayed in chat-thread-style using Kinetise LIST widget.

First, you need to set up Watson Conversation on IBM Bluemix. We are not covering IBM Bluemix registration process in this tutorial. Simply set up Bluemix account, and launch Watson Conversation service.

Go back to Kinetise to start building the app. For quick cleanup – delete the footer, add vertical container and set its height to MAX (in Layout Tab), to fill whole Body of your screen. To send user inputs to Watson Conversation, you will need FORM widget. So drag it to your app and change its layout to “horizontal”. You might want to notice, the FormID of this TextInput field, which is “textinput1”. Switch back to editing the whole FORM widget and set it to send data to RESTful API. It’s time to configure API connection to Watson Conversation, so open RequestSettings by clicking icon next to URL address field.

CONNECTING TO WATSON CONVERSATION API

There are two sources for information needed:

    • Watson Conversation Deploy section – visit /watson-conversation.ng.bluemix.net/, select “Car Dashboard – Sample” template and go into Deploy section to see Service Credentials. For this tutorial we are using the pre-defined template, because it is already set-up, contains various chatbot replies, so we won’t waste time for this.
    • Watson Conversation API Reference – /watson-api-explorer.mybluemix.net/apis/conversation-v1#!/Message/message. Specifically “Message” API-call, because we will use only this one in this tutorial: “Get response to a user’s input”.

Here are exact steps to establish the connection:

    1. Make sure the API-call is made with POST method.
    2. Paste “Workspace URL” from your Watson Conversation Deploy page into URL field. Something like this: /gateway.watsonplatform.net/conversation/api/v1/workspaces/3916c79e-b94b-476e-8fc8-f16c9a43f8a6/message/
      The part between /workspaces/ and /message/ will be different in your case for sure.
    3. Switch to Authorization tab.
    4. Select Basic Auth and paste “Username” and “Password” from Watson Conversation Deploy page into relative fields.
    5. Steps 1-4 are shown in the screen below. Now, click blue  button – if you did everything correctly, you should see “Missing version query parameter” response.
    6. Switch to Params tab. Add “version” : “2017-05-26”. Click blue TEST button again to see much longer server response.
    7. Switch to Body tab. Add “context”:”{{GetLocalValue(context)}}” into Body parameters. The “context” variable is returned after initial contact with Watson Conversation API, and stored as local variable.
    8. Default Kinetise FORM data structure doesn’t match Watson Conversation API, so this is where Embedded API Adapter (still in Body tab) is required. It will transform this default data structure into a shape expected by Watson Conversation API. Following Watson API guidelines, paste this into Request Body Transform field:
      {
        "input": {
           "text": .form.textinput1}
      }
      + (.params.context | if . == "" then null else {"context":.|fromjson} end)
      

      Note, that Watson API example includes “text”: “Turn on the lights”, while you need “text”: .form.textinput1 – to submit the value typed in by the user.

    9. Click green .

PARSING RESPONSE

Ok, now that the data has been sent, we need to receive and parse the response. Still, in the Request Settings popup and Body tab, scroll down and paste this into Response Body Transform field:

def settime: reduce range(length) as $i (.; .[$i].time = (now + $i|tostring));
{
 "localDB" : [{
   "tableName": "Default",
   "mode": "append",
   "data": [
     {"time" : now|tostring, "message" : .input.text, "from" : "me"},
     {"time" : now|tostring, "message" : .output.text[]}
  ] | settime
 }],
 "applicationVariables" :{
  "context":.context|tostring
}}

Click green .

This will inject two or more records to Local (on-device) database: one with the text user has entered (yes, Watson API includes it in the response), second with chatbot’s answer and more – because this chatbot can return more than one reply. Column “from” is used to differentiate user entries from chatbot replies. Column “time” is used for sorting the messages.

And you are storing whole “context” object, which has to be used in further API-calls, to prevent conversation from “getting lost”. We already implemented using it two steps before, so nothing more to do here.

What happens here? We are 4507969274, you can check the detailed tutorial about it. For better understanding on how to work with data and variables, please also take a look and another tutorial about Creating and Using Local Variables.

Click blue .

We’re done with the architecture, so let’s test it now by sending “Hello” message. RIGHT-mouse-click  button to actually submit the message to Watson Conversation API. Make sure you really submit this first message – if you don’t, some values will not show up further down the tutorial.

DISPLAYING THREAD

    1. Add LIST widget now, delete IMAGE widget  from the first item and lower TEXT widget next to it.
    2. Make LIST widget read data from Local Database
    3. Click “Settings” icon to enter “Local Database Request Settings”. Set sorting there: with “time” column, in DESCending order. NOTE: If you didn’t send that first message in previous paragraph, “time” will not show up in sorting dropdown. Click .
    4. Set items count to 100.
    5. Invert the list.
    6. Switch to Layout Tab and set LIST’s height to MAX.

    STYLING THREAD

  1. Now we need to style the list into chat-thread view. Do this:
    1. Start editing that TEXT widget in first item of the list (actually it is last after using that “Invert List” feature a few steps back).
    2. In General Tab select “message” from the dropdown list of available Local DB columns. NOTE: If you didn’t send that first message in two paragraphs before, “message” will not show up in dropdown.
    3. And disable MaxLines limiter.
    4. In Layout Tab set the following:
      • background color: blue (or other of your choice)
      • width: MIN
      • padding left and right: 2
      • radiuses all: 3
    5. Once again, go back to editing LIST widget, in General TAB. Enable “Extra Options” and “Item Templates“.
    6. Click , name it something like “fromme”. Parametrize it like this:
    7. This should have created separate item template, so now you have two: one for messages from the user and one for chatbot responses.
    8. “fromme” should now be active-for-editing item-template. Select Text widget inside this item-template. It is easiest to catch it from the structure tree.
    9. Make those changes:
      • text alignment to RIGHT (General tab)
      • background color to something else, yellow, perhaps? (Layout tab)
      • widget alignment to RIGHT (Layout tab)

Your chatbot is ready!

Injecting data from the backend to Kinetise mobile app

There is variety of ways data, information and variables can be delivered to the mobile app to be stored for later use. When making API-call via POST or PUT method, and server responds with status 200 “success”, the mobile app can read and parse response body payload. Below is example body of such response:

{
 "message": {
   "title": "Info",
   "description": "Message to show to end-user"
 },
 "sessionId": "123456SessionId",
 "expiredUrls": [
   "/sampleurl/api/1",
   "/sampleurl/api/2"
 ],
 "applicationVariables": {
   "_USER_ROLE": "ADMIN"
 },
 "localDB": [
   {
     "tableName": "table name",
     "mode": "append|create",
     "data": [
       {
         "fieldName1" : "fieldValueA",
         "fieldName2" : "fieldValueA",
         "fieldName3" : "fieldValueA"
       },
       {
         "fieldName1" : "fieldValueB"
       },
       {
         "fieldName1" : "fieldValueC",
         "fieldName2" : "fieldValueC"
       }
     ]
   }
 ]
}

“message” – a popup will be displayed to the user after parsing the response is complete.

“sessionId” – delivers up-to-date sessionId token, which can be used in future API-calls for security and identifying user.

“expiredUrls” – some widgets in the app (especially LIST widgets) can be set to cache data on mobile device to avoid making unnecessary API-calls and ensuring smooth, native user experience. “Content refreshing policy” can be set to, let’s say, 10 hours. But what if the data changes on the backend in the meantime? Mobile app will not make API-call to fetch new data before 10 hours timeframe passes. “expiredUrls” is a parameter informing the app which cached data should be refreshed immediately, without waiting for the timeframe to pass.

“applicationVariables” – delivers values to application variables or creates those variables on the mobile app.

“localDB” – delivers set of data, which will be stored in local database within mobile app. Please note, you need to select either ‘append’ or ‘create’ mode. “fieldnameX” is a name of the column.

To quickly test how these features work, you might want to use www.mocky.io.

289-792-5631

1. You need two tables in Kinetise CMS, so create them:
* “temp”
* “selections”

2. In “selections” table add some values and numbers into first two columns, like this:

3. In “temp” table, add new column: type: Relation, name: “dropdownselections”, related table: “selections”. Like this: 

4. Now click  and check all selections from “selections” table:

5. You can close KinetiseCMS now and proceed to the mobile app editor.

6. Add LIST widget, reduce its items count to 1, remove Show More, delete all widgets from the item and add FORM widget into that first item of LIST widget. At the end this is what you should see:

7. On structure tree select LIST widget and make it load data from KinetiseCMS -> “temp” table. Click on that RequestSettings icon.

8. Make sure to add this to Params: “_dropdown”:”dropdownselections” – the latter is the name of the relation which was set earlier. Click blue SAVE button at the bottom of Request Sections popup to confirm.

9. Now, add DROPDOWN to your FORM.

10. Set Dynamic source for dropdown selections and make it point to “$.dropdownselections” node and also “$.title” and “$.description” columns. If you don’t have these available, you probably skipped some step before.

11. Right-click on the dropdown and you should now see selections from KinetiseCMS.

 

That’s it!

How to create First-Use intro section?

The goal is to create special screen or screens in the application, which user can be navigated to only when he logs in to the application for the very first time. This is very often used to show apps tutorials or intro.

We will use User-Roles mechanism for this. Some preparation is needed first.

Preparation

1. Let’s start by creating a set of screens. First, let’s rename the first screen to “Intro1”. Make sure to click green OK button. 2. Now, let’s create “Intro2” and “Home” screens.3. Open Basic Application Settings by clicking tab on the left, go to Auto-Navi tab and remove “Intro” screens from global app navigation, and navigation from them, as well. When asked “Do you want to disable or remove the Auto Menu from this screen?” answer – REMOVE.4. It might be good to modify header of the app, so it displays current screen name on each screen. Left-click that “AppName” on the header and change {{GetAppName}} into {{GetScreenName}}.5. On “Intro1” screen let’s add custom button navigating user to “Intro2” screen. To do this, add Text widget, make it say “Proceed to Step 2 >>” and in Events tab set action to navigate to “Intro2” screen. This is a place when screen transition effect can be added, too.6. On “Intro2” screen add similar text button, saying “Finish Intro >>” and navigate the users to “Home” screen.
7. On Splash Screen let’s add Login with Facebook.

Setting up the feature

Now, the tricky part. How to navigate users so they automatically skip the intro screens and land in “Home” screen each time, except for the first launch?

8. We’ll use USER ROLES mechanism for that. Click on LOGIN-WITH-FACEBOOK button and in its EVENTs tab, declare that users with role “notfirsttime” should be navigated to “Home” screen. All other users, meaning – first time users – will be navigated to the “Intro1” screen. Make sure you click that orange ADD button.
9. After user taps LOGIN-WITH-FACEBOOK button, application logic checks the value of “userrole” variable and based on this value navigates users to one screen or another. Usually, this user role should be returned by the authenticating server in a response to login request, but if it is not, we can play with it locally.
10. Go to “Intro2” screen, find “Finish intro” button and change its action. Instead of navigating users to “Home” let’s make it set value of “_USER_ROLE” variable to “notfirsttime”. NOTE – it is case sensitive! As a secondary action let’s again set it to navigate users to “Home” screen.That’s it! When logging in for the first time, users will land on the “Intro1” screen, go through the intro and set “userrole” value to never return to the Intro section again.

TESTING HINT: to test it quickly you can add:
1. Logout button to each screen
2. Text widget saying this: “User Role: {{GetLocalValue(_USER_ROLE)}} – it will display current value of the variable. Add it to each screen, including “Splash Screen”

Play around, see how it works!

How to define logic deciding which screen to go to

The scenario is this: user enters a value, and app navigates hime to screen A or screen B, depending on his input.

The order of events would be like this:
a. User inputs data in a FORM widget.
b. Mobile app creates Local Variable to store his input.
e. Mobile app performs a logical check on this Local Variable (in condition in JavaScript) and acts accordingly.

    1. We need to create two screens named “A” and “B”.
    2. On the “Main screen”, add FORM widget, which by default includes TEXTINPUT subwidget. In Widget Properties panel select destination for the data user inputs: Local / To Local Variables.
    3. LEFT-MOUSE CLICK that TEXTINPUT widget (or select it on the Screen Structure tree) to open its Widget Properties panel. Remember its FormID, in our example: “texinput1”.
    4. Now LEFT-MOUSE CLICK the SEND button (or select it on the Screen Structure tree) to open its Widget Properties panel. We’ll define what should happen after user submits his data. Switch to EVENTS tab. This is a FORM button, so basic action – Save To Local Values – has been predefined earlier and cannot be changed here – but we are going to add secondary action here. From the dropdown select a secondary action: “Add JavaScript code”.
    5. The code should look like this:
       if (app.storage.get('textinput1') > 10) {app.screen.go('screen149518844013355')} else {app.screen.go('screen149518844630157')}

    6. What the code does? It checks if the value of “textinput1” is higher than 10, and if it is, navigates user to one screen and if not – to another. Before launching this, please check what are screen values for your app and replace them (look just below the JavaScript).
    7. To try it out, just enter any number into the TEXTINPUT field and RIGHT-MOUSE-CLICK on the button – you’ll be navigated to screen A or B depending on what you’ve entered.