Using your generated Android SDK

This article is now deprecated. SDK usage instructions are now contained in the generated SDK.

See the new APIMATIC docs.

In this article, we will walk you through the generation of the SDK and how to use it.

The following covers the following aspects:

1. Setting up the environment
2. SDK generation instructions
3. SDK installation instructions
4. Creating a sample application that uses our SDK

Note: The code for this tutorial is provided as a zip file available for download here.

1. Setting up the environment:

2. SDK generation instructions:

After choosing Android platform, as shown in Figure 1, a zipped file will be downloaded. This file contains the code for the APIMATICCalculator library we will be using in our project. 

3. SDK installation instructions:

In order to use your library, you have to unzip it first. 

Extract the unzipped file to a new folder, as shown in Figure 2. 

Building:

In order to use your library, you need to build it first.

Open your android studio, using the "import project" option, provide a path to the unzipped archive for the generated code. 

In order to build, choose "make project" from the build menu, as shown in Figure 3.

Notice the library hierarchy on the left of your screen.  

The console at the bottom of the screen shows your build progress. It will come up with a "BUILD SUCCESSFUL" message in case of correct building completion. 

4. Creating a sample application:

The following section explains how to create a new android application that uses your generated apimatic calculator library.

 4.1 Starting a new project

To start a new project, choose

File -> new -> new project

Provide your application name "MyCalculator", as shown in Figure 4.

After clicking "next", tick on "Phone and Tablet", then "next" again.

Choose an activity (e.g Blank activity), then "next" and "finish".

We just created our new Android project! 

4.2 Adding your library to your project:

To use your library, you need to include and compile the library in your project.

To achieve this, first you need to copy-paste your APIMATICCalculatorLib inside your "MyCalculator" folder.

Figure 5 shows your folder contents after adding your library. 

The APIMATICCalculatorLib will show in your folder hierarchy on the left-hand section. 

To include your library in your new "MyCalculator" project, go to your "settings.gradle" and include our apimatic library by adding the following line: (as shows in Figure 6)

include ':APIMATICCalculatorLib' 

Figure 6: Including our library.

Now the "settings.gradle" file, which belongs to our "myCalculator" project has "app" and "APIMATICCalculatorLib". The "app" is the application where we will add our code that uses our library. This means our project uses both; the app and the library, hence we have to include them both.  

On your Android studio, navigate to your "build.gradle" file for the "app" module, as shown in Figure 7. 

Figure 7: "build.gradle" file.

Make sure you choose the right file since there is a different "build.gradle" file for every module in the project, in addition to one build file for the whole project. Therefore, we have three "build.gradle" files for this project.

Figure 7 shows the "build.gradle" file for the "app" module after the following steps has been done:

1. Inside the "defaultConfig" block, change the "minSdkVersion" to "18" if it is lower than that. The reason is that our apimatic library has a "minSdkVersion" value of "18", and so the projects should be using the same version to be in sync.
2. Add the "packageOptions" block with the three exclusions. This is to avoid conflicts with the apimatic library.
3. In the "dependencies" block, add the the last "compile project(":APIMATICCalculatorLib")" statement shown. This compiles the apimatic library that has been included to the project.

We now included and compiled our library inside our project. It is ready for use! 

4.3 Using your library in your project:

To use the library, we need to instantiate its objects and invoke their functions.

For the  calculator to run, we need to invoke the asynchronous method getCalculateAsync(), shown in Figure 8, on the controller object.

This method takes two parameters:

1. A GetCalculateInput object which contains two doubles and an operation name of type enum (e.g. SUM) 
2. An APICallBack object, which instantiates an interface. As with any interface, we have to provide an implementation for its methods. In this case we have two methods; onFailure() and onSuccess(), which are executed depending on the result of running the program

Figure 9 shows how your MainActivity class should look like after doing the following steps in order:

1. Inside your onCreate method, initialize your Configuration (line 24)
2. Instantiating the SimpleCalculatorController (line 25)
3. Invoking the getCalculateAsync() method on it (line 31)
4. Defining the GetCalculateInput object parameter for the method (lines 26-29) 
5. Providing implementation for the APICallBack object (lines 32-42)
6. Defining a TAG string (line 17). 

In both methods onSuccess(), and onFailure(), an "HttpContext" object is injected as a parameter. Context objects have raw information about the HTTP request and response.

• In onSuccess(), “String response” is the result of the operation performed by the calculator.
• In onFailure(), “Throwable error” is an exception object that can be used to track down the error encountered.

The "TAG" string is used to identify your log message in the console. We assigned it to "myCalculator" so we can easily see the result or error logged to our console. (lines 34 and 40)

Note : This is a basic Android application to show how to use your SDK. The means used to display the result and/or error messages, the appearance and complexity of your application is up to you to control, improve and implement.

You are ready to run the application.

4.3 Running your application:

To run this application, click on the green play button on the top toolbar.  

Figure 10 shows the result with the right tag logged on the bottom-left window (in pink).

Go to top

Download files below.