ExternalAPI Introduction

ExternalAPI is the object used when the connection between the Nexacro app and external app is required. You can transmit messages to a specific app for the execution or perform a specific function. Of course, the connection will all apps is not applicable, and you can only connect with apps that have logic to receive and process messages sent from the Nexacro app.

Android and iOS differ in the communication method between apps ,and ExternalAPI enables this to be carried out with the same method, regardless of the environment. However, there is only a slight difference in the ID setting used to identify the target app when calling the method. In Android, the package name is used as ID, and in iOS, the custom URL scheme is used. Other argument settings are the same, though. The following shows an example of calling the execExtAPI method of the ExternalAPI object in the Android and iOS environments.

//Android
this.ExternalAPI00.execExtAPI("100", "com.nexacro.ExternalAPITest", "fn_Chk", "aa bb 'cc c' dd");

//iOS
this.ExternalAPI00.execExtAPI("200", "ExternalAPITest://", "fn_Chk", "aa bb 'cc c' dd");

Naturally, Android or iOS apps need to implement the logic to process the request of the code above. In Android, the processing of the broadcast receiver is required, and in iOS apps, the processing of the custom URL scheme is required.

This chapter describes how to send messages or call API from the Nexacro app to other apps. Please refer to Creating the Test App for how to create the Android and iOS apps to communicate with the Nexacro app for testing, or the app demo project file.

Checking Access to External App

It is good to first check if access is available before connecting with external apps. Sending a message without knowing whether the app you want to connect is installed or the application ID is correct will only cause system performance degradation. In this case, the method that is easy to use is isAccessible. The isAccessible method uses the package name (Android) or custom URL scheme (iOS) to check if access to other apps is available.

${sample}

The following is an example of using the isAccessible method to check whether access to the external app is available. Enter the Application ID of the app to check access and touch the Access button. In the Android environment, enter the package name, and in the iOS environment, enter the custom URL.

If access to other apps is available, the onsuccess event occurs, and if not, the onerror event occurs with the result log displayed in TextArea.

${sample_element}

ExternalAPI > isAccessible

This is the method that checks if access to a specific app is available. It calls the application ID in Android and the URL scheme in iOS as the argument.

ExternalAPI > onsuccess

This is the event that occurs when the task requested by the ExternalAPI object is successful.

ExternalAPI > onerror

This is the event that occurs when the task requested by the ExternalAPI object fails.

${sample_step}

Add the ExternalAPI object. The added object can be checked in the Invisible Object window.

Place the Static, Button and Edit components to receive the Application ID or custom URL scheme of the target app, and TextArea to display the result appropriately as shown in the example figure.

Components and objects used to configure the screen are as follows.

Write the onload event function of Form as follows. When calling the isAccessible method, different arguments must be set depending on the OS. Therefore, check the OS and set the default argument value for the Edit component.

this.example_externalapi_01_onload = function(obj:nexacro.Form,e:nexacro.LoadEventInfo)
{
	var strOS = nexacro.System.osversion;
	
	if(!strOS.toLowerCase().search(/android/))	//Android
	{
		this.edt_appid.set_value("com.nexacro.extAPITest");
	}
	else if(!strOS.toLowerCase().search(/ios/))	//iOS
	{
		this.edt_appid.set_value("extAPITest://");
	}
	else
	{
		this.edt_appid.set_value("");
	}	

	this.TextArea00.set_value("");
};

Write the onsuccess event function as follows. It is called when the task requested to the ExternalAPI object is successful.

this.ExternalAPI00_onsuccess = function(obj:nexacro.ExternalAPI,e:nexacro.ExternalAPIEventInfo)
{
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "- ExternalAPI onsuccess");
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > obj : " + obj);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.eventid : " + e.eventid);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.reason : " + e.reason);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.recvid : " + e.recvid);		
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.recvdata : " + e.recvdata +"\n");
};

Write the onerror event function as follows. This is the event that occurs when the task requested to the ExternalAPI object fails.

this.ExternalAPI00_onerror = function(obj:nexacro.ExternalAPI,e:nexacro.ExternalAPIErrorEventInfo)
{
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "- ExternalAPI onerror");
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > obj : " + obj);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.eventid : " + e.eventid);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.statuscode : " + e.statuscode);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.errormsg : " + e.errormsg +"\n");	
};

Write the onclick event function of the Access button as follows.

this.btn_isaccessible_onclick = function(obj:nexacro.Button,e:nexacro.ClickEventInfo)
{
	this.ExternalAPI00.isAccessible(this.edt_appid.value);
};

Write the onkeydown event function of the Edit component as follows. It is processed as if the Access button was touched when the user enters in Edit and presses the Enter key with the soft keyboard without touching the Access button.

this.edt_appid_onkeydown = function(obj:nexacro.Edit,e:nexacro.KeyEventInfo)
{
	var strURL = this.edt_appid.value;
	
	if(e.keycode == "13")	//Enter key
	{			
		if(nexacro._isNull(strURL) || strURL == "")
		{
			this.edt_appid.setFocus();
		}
		else
		{
			this.btn_isaccessible_onclick();
		}	
	}
};

Install the app to connect with the Nexacro application. For the Android app, the Application ID must be set, and for the iOS app, the custom URL scheme must be set.

Depending on the OS, touch the Access button after entering the Application ID or custom URL scheme to check whether the execution is normally performed. If it is successful, then the onsuccess event is displayed, and if fails, then the onerror event log is displayed in TextArea at the bottom.

Calling External API

You can use the execExtAPI method to perform external apps or use a specific function. If you use the execExtAPI method to transmit a message, then the external app receives and processes it to transmit the result.

${sample}

The following is an example of using the execExtAPI method to transmit and receive data from external apps. Set the argument and touch the Go button. If the data transmission is successful, then the onsuccess event occurs, and when data is received from the external app, the onrecvdata event occurs.

The following is the log message of the external app that received the message from the Nexacro application.

11-22 20:48:37.939 10661-10661/com.nexacro.extAPITest I/nexacro: >> [com.nexacro.extAPITest] message received.
11-22 20:48:37.941 10661-10661/com.nexacro.extAPITest I/nexacro: - sender:com.tobesoft.np17demodev.extAPI
11-22 20:48:37.942 10661-10661/com.nexacro.extAPITest I/nexacro: - recvID:1
11-22 20:48:37.943 10661-10661/com.nexacro.extAPITest I/nexacro: - apiname:dummyApi
11-22 20:48:37.943 10661-10661/com.nexacro.extAPITest I/nexacro: - params:arg1=text arg2=1234

${sample_element}

ExternalAPI > execExtAPI

This is the method that calls the API of the external app. You need the application ID, URL scheme, or API name to call to identify the app you want to call. Parameters can also be transmitted if necessary.

ExternalAPI > onrecvdata

This is the event that occurs when data (character string) is received from the app called with the execExtAPI method.

${sample_step}

Add the ExternalAPI object. The added object can be checked in the Invisible Object window.

Place the Static, Button, and Edit components to receive the execExtAPI method argument and TextArea to output the result appropriately as shown in the example figure.

Components and objects used to configure the screen are as follows.

Write the onload event function of Form as follows. When calling the execExtAPI method, different Application ID arguments must be set depending on the OS. Therefore, check the OS and set the default argument value for the Edit component.

this.example_externalapi_02_onload = function(obj:nexacro.Form,e:nexacro.LoadEventInfo)
{
	this.TextArea00.set_value("");
	var strOS = nexacro.System.osversion;
	
	if(!strOS.toLowerCase().search(/android/))
	{
		this.edt_appid.set_value("com.nexacro.extAPITest");
	}
	else if(!strOS.toLowerCase().search(/ios/))
	{
		this.edt_appid.set_value("extAPITest://");
	}
	else
	{
		this.edt_appid.set_value("");
	}	
};

Write the onsuccess event function as follows. It is called when the task requested to the ExternalAPI object is successful.

this.ExternalAPI00_onsuccess = function(obj:nexacro.ExternalAPI,e:nexacro.ExternalAPIEventInfo)
{
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "- ExternalAPI onsuccess");
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > obj : " + obj);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.eventid : " + e.eventid);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.reason : " + e.reason);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.recvid : " + e.recvid);		
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.recvdata : " + e.recvdata +"\n");
};

Write the onerror event function as follows. This is the event that occurs when the task requested to the ExternalAPI object fails.

this.ExternalAPI00_onerror = function(obj:nexacro.ExternalAPI,e:nexacro.ExternalAPIErrorEventInfo)
{
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "- ExternalAPI onerror");
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > obj : " + obj);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.eventid : " + e.eventid);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.statuscode : " + e.statuscode);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.errormsg : " + e.errormsg +"\n");	
};

Write the onrecvdata event function as follows. This is the event that occurs when the message is received from the external app. The received message can be checked in the e.recvdata property.

this.ExternalAPI00_onrecvdata = function(obj:nexacro.ExternalAPI,e:nexacro.ExternalAPIEventInfo)
{
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "- ExternalAPI onrecvdata");	
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > obj : " + obj);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.eventid : " + e.eventid);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.reason : " + e.reason);
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.recvid : " + e.recvid);		
	this.TextArea00.set_value(this.TextArea00.value + "\n" + "   > e.recvdata : " + e.recvdata +"\n");	
};

Write the onclick event function of the Go button as follows. Call the execExtAPI method after setting the argument received from the user.

this.btn_go_onclick = function(obj:nexacro.Button,e:nexacro.ClickEventInfo)
{
	var strRecvID = this.edt_recvid.value;
	var strApplicationID = this.edt_appid.value;
	var strAPI = this.edt_apiname.value;
	var strParams = this.edt_parameter.value;
	
	this.ExternalAPI00.execExtAPI(strRecvID, strApplicationID, strAPI, strParams);
};

Check that the app you want to connect with the Nexacro app is installed on the mobile device. If it is installed, enter the argument to be set in the execExtAPI method and touch the Go button to check if it is executed normally.

When the execution is successful, the onsuccess event occurs and when it fails, the onerror event log is displayed in TextArea at the bottom. When the message is received from the external app, the onrecvdata event occurs.

Creating the Test App

Android and iOS provide methods for connection between apps according to each environment. These enable connections, such as message or data transmission between apps or calling apps. If you implement the processing logic in the app as in this process, then the connection with the Nexacro app is also available.

This chapter describes how to create the test app that can transmit data and call API with the Nexacro app. The test app is created with Android Studio and Java in Android, and xcode and Object C in iOS. As it is important to create the interface that allows you to send and receive messages, the user can create apps in Kotlin or Swift appropriately suited to the environment.

Android

In Android, intents and broadcast receivers can be used for communication between apps and components. The intent plays the role of transmitting data, such as requests and messages between components of the app, and the broadcast receiver plays the role of receiving the intent to the Android system.

When the app transmits the intent containing the message with broadcast to the Android system, the app can receive it through the broadcast receiver from the app. Among the various broadcast messages that are transmitted to the Android system, the message to be received can be selected through the intent filter registered in the app. Therefore, what type of messages to be received must be registered to the Android system in advance, and this can be done through the manifest.

The demo project code with examples can be downloaded from the link below.

demo_android_ExternalAPITest

Create the Android app project by referring to the Develop App Project chapter of App Development & Execution (Android) in the Nexacro Platform 17 Deployment Guide.

When creating the project, set the package name to com.nexacro.ExternalAPITest. The package name is important, as it is used as the ID in communication with the Nexacro app.

Since this is not the app that requires a separate screen, do not add activities and do not set resource-related settings, such as icons and splash images. Also, since it is not the Nexacro app, do not set the Nexacro Platform library and nexacro config.

Write the strings.xml file that declares the character strings to be used in the app. The strings.xml file is usually automatically created when the project is created. If it is not in the res > values directory, then it can be created by executing [New > XML > Values XML File] from the File menu of the toolbar or the context menu of the project explorer.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="hello">Hello World, ExternalAPITest Activity!</string>
    <string name="app_name">ExternalAPITest</string>
</resources>

Create the layout file to be used on the first screen to display the welcome message when running the app. Create through the [New > XML > Layout XML File] menu. Set Layout File Name as main and Root Tag as LinearLayout. The created file can be checked in the res > layout directory, and modify it by referring to the code below.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:orientation="vertical" >

    <TextView
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:text="@string/hello" />

</LinearLayout>

Create the first screen to display the Hello message when running the app. Inherit the Activity class and declare the ExternalAPITestActivity activity class.

package com.nexacro.ExternalAPITest;

import android.app.Activity;
import android.os.Bundle;

public class ExternalAPITestActivity extends Activity {
    /* Call when the activity is first created */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
    }
}

Create the extAPIReceiver class that implements the broadcast receiver.

The broadcast receiver can be implemented by inheriting the BroadcastReceiver class, and the onReceiver method must be defined inside the class. This method is called automatically when the desired broadcast message arrives.

Messages are transmitted as the intent object, so if there is a message you want to receive, then you need to register the intent filter in advance. In other words, you need to let the Android system know what intents you want to receive using the intent filter in advance. The intent filter can be registered in the manifest file.

package com.nexacro.ExternalAPITest;

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import android.util.Log;

public class ExternalAPIReceiver extends BroadcastReceiver {
  
   @Override
   public void onReceive(Context context, Intent intent) {
      // Output the contents received from the intent to log when the broadcast message is received
      Log.i("nexacro", ">> [com.nexacro.ExternalAPITest] message received.");
      Log.i("nexacro", "- sender:" + intent.getExtras().getString("sender"));
      Log.i("nexacro", "- recvID:" + intent.getExtras().getString("recvID"));
      Log.i("nexacro", "- apiname:" + intent.getExtras().getString("apiname"));
      Log.i("nexacro", "- params:" + intent.getExtras().getString("params"));
      
      // Create the intent and transmit it with broadcasting
      Intent callExtAPI = new Intent(intent.getExtras().getString("sender"));
      callExtAPI.putExtra("recvID", intent.getExtras().getString("recvID"));
      callExtAPI.putExtra("recvdata", "This is a message from com.nexacro.ExternalAPITest");
      context.sendBroadcast(callExtAPI);
   }
}

When the extAPIReceiver class receives the broadcast message, it extracts the data received from the intent object, creates a new intent object, and then transmits it to the Nexacro app with the broadcast.

Set the activity, broadcast receiver, and the intent filter in the AndroidManifest.xml file that contains app-related configuration information.

First, register the ExternalAPITestActivity activity to be used as the first screen when running the app. Then, register the broadcast receiver to receive messages from other apps on the mobile device, and register the intent filter below it. The broadcast receiver is also an application component, so when you create a new broadcast receiver, you must register it in the manifest file for the system to be able to identify it.

There are two methods to register the broadcast receiver. One is the static receiver that is registered and used in the manifest file, and the other one is the dynamic receiver that registers/unregisters using the registerReceiver/unregisterReceiver methods in Java code.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.nexacro.ExternalAPITest"
    android:versionCode="1"
    android:versionName="1.0" >

    <application
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name" >
        <!-- Activity Settings -->
        <activity
            android:label="@string/app_name"
            android:name=".ExternalAPITestActivity" >
            <intent-filter >
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
        <!-- Broadcast Receiver and Intent Filter Settings -->
        <receiver android:name="com.nexacro.ExternalAPITest.ExternalAPIReceiver" android:enabled="true">
            <intent-filter>
                <action android:name="com.nexacro.ExternalAPITest.extAPI" />
            </intent-filter>
       </receiver>
    </application>

</manifest>

Build the app in Android Studio and install it on the mobile device by referring to the Build chapter of App Development & Execution (Android) in the Nexacro Platform 17 Deployment Guide.

Check that both the test app created and the Nexacro demo app are installed and run the Nexacro demo app. Select [ExternalAPI > Calling External API] from the menu, check that the Application ID is set the same as the package name of the test app, and then touch the Go button.

The log message is output in TextArea at the bottom. When it is successful, the onsuccess event and the onrecvdata event occur sequentially. The onsuccess event occurs when calling the execExtAPI method is successful, and the onrecvdata event occurs when data is received from another app. When calling the method fails, the onerror event occurs.