Android

Android Installation Guide

Installing CoPilot Android version

1. You will need to download the CoPilot application and SDK files from the CoPilot Portal.

2. After unzipping the downloaded packages, you will need to install the CoPilot .apk to your device. Once installed the first run will require a product key to be entered and map data can be either downloaded in the application or pre-loaded prior to launch (maps would be downloaded from the CoPilot Portal).

Please note you can also return to the CoPilot Portal at any time for the latest SDK and to install the latest CoPilot app updates.

SDK Integration Overview

CoPilot SDK for Android can be used for Java or native integration.

The CoPilot SDK Package contains the following:

1. Header files (alkmsg.h for Native and AlkMsg.java for Java integration)

2. Static Library which contains all the API (Libalksdk.so )

3. Sample Application (SDKApp)

Please note that to connect the SDK to CoPilot you will require a supported version, this is not available via the Google Play Store applications.

SDK Library

1. Libalksdk.so is a static library and can be used on Android 4.1 and above.

2. SDK and CoPilot communicate using TCP/IP connection with localhost. Client application must have INTERNET permission defined in AndroidManifest file. Without this permission, SDK will not able to communicate with CoPilot and all APIs will fail.

   <uses-permission android:name="android.permission.INTERNET"></uses-permission>
   

3. AlkMsg.Java file must be place in com.alk.sdk package otherwise calling SDK functions will generate function not found exception.

4. Messaging between Client and CoPilot can be started by using function Msg_StartUp.

5. Before using any API make sure you use Msg_IsConnected to ensure that the connection is established between client and CoPilot. The only exception to using Msg_IsConnected before an API is when using Msg_StartUp and Msg_HasStarted.

6. Client application can use Msg_UpdateOption to add callback function for given message. Client application needs to make sure that they remove the callback when they no longer need it. Client application needs to make sure that all the callbacks are removed before calling Msg_ShutDown.

Third Party Application Development

Please refer to the SDK API documentation, to ensure the APIs you’re looking to integrate are supported on the Android platform. The following are guidelines for Android specific integration.

1. Your project should include AlkMsg.java header files which contain the declaration of all SDK API for Java development and alkmsg.h for native development.

2. Your project should add libalksdk.so and load before using any SDK API.

3. CoPilot can be launched or viewed by using the following package name and class name.

   • Package Name: com.alk.copilot. Please note that this package name can vary slightly

   • Class Name: com.alk.copilot.Copilot

4. CoPilot’s default behavior when hiding is to return to the home screen of the Android device. However, if you want to show the integrating application when the user presses the hide or back button within CoPilot, the client application will need to pass additional data when CoPilot starts.

To return to the client application upon hiding CoPilot, the client application needs to:

1. Subscribe for a MSG_IDT_HIDE event and listen. It will be triggered when the user presses the minimize button on CoPilot.
2. The client application needs to bring its activity to foreground once it receives a MSG_IDT_HIDE.

CoPilot Back Button Behavior

If the driver is on any of the navigation screens and the driver presses the back button, CoPilot’s default behavior is to prompt to close the application. If you would like the behavior to simply minimize the application you will need to add the following to either the user.cfg or product.cfg

[User Settings]
"BackButtonPromptsToMinimize"=0

CoPilot Behavior In Background

In order to communicate with client application and CoPilot, both applications must be running. Android will destroy the activity if activity is not in foreground including CoPilot. CoPilot is designed such that even it goes in background, it will keep running if one of the following condition is satisfied.

1. Add the below to user.cfg or product.cfg to ensure that CoPilot application is always running regardless of current destination [User Settings] "BackgroundNavAlwaysOn" = 1

2. Add the below to user.cfg or product.cfg to ensure that CoPilot application is always running when a destination is set [User Settings] "EnableBackgroundNav" = 1

It is advisable that CoPilot should have any of the above settings in order to run efficiently in background otherwise Android may destroy the CoPilot activity and client application may not communicate with CoPilot.

Opening SDKApp to Android Studio

1. Launch Android Studio

2. Open project from the file menu item

3. Android Studio prompts file or project dialog to select the existing project

4. Select the root directory of the project and click “OK” button (i.e C:_repo_application_AndroidStudio)

5. Update sdkapp libs in Android Studio by doing right click on jnilibs and select “show in explorer” (e.g libalksdk.so at path C:_repo_application)

6. In order to build sdkapp with Android Studio, we need to do the following project dependencies with build.gradle(module app) 6.1.:

sourceSets { main {
    manifest.srcFile '../../SDKApp/AndroidManifest.xml' java.srcDirs =
    ['../../SDKApp/src'] resources.srcDirs = ['../../SDKApp/src'] aidl.srcDirs =
    ['../../SDKApp/src'] renderscript.srcDirs = ['../../SDKApp/src'] res.srcDirs
    = ['../../SDKApp/res'] assets.srcDirs = ['../../SDKApp/assets']
    jniLibs.srcDirs = ['../../SDKApp/libs'] } }

Getting Started with your project

Installing the sample application from an APK

Installing the sample app follows similar steps as above. The compiled sample application is meant to act as a reference for your wrapper application.

1. Download the CoPilot SDK download and extract the contents. The SDKSample.APK file can be found in the following folder: .../SDK Sample Application/sdkapp/

2. Follow the instructions above to install a third party APK.

Background on how applications communicate with CoPilot

Communication with CoPilot is done over a TCP/IP connection against the localhost, as such any application looking to communicate with CoPilot will need to ensure it has the INTERNET permission in their Android manifest file.

The controlling application (your application, our sample application etc.) uses two files to communicate with CoPilot. First the AlkMsg.java file, this acts the method declaration for the APIs that can be used to communicate with CoPilot. The second file is the libalksdk.so file, this is a shared object that contains all of the APIs for CoPilot. Both would need to be included and loaded before any communication can be done with CoPilot. These two files effectively act like a remote control to CoPilot, the controlling application “pushes buttons” and CoPilot responds and provides content back.

Android SDK Setup

AlkMsg.java should be placed in a com.alk.sdk package within your controlling application. It can be found in the Java folder in the CoPilot download.

libalksdk.so can be found in the Library folder in the CoPilot download and is split into the relevant architectures. For ease, this folder’s contents can be copied to <your project>/app/src/main/jniLibs/ (Android Studio only). Otherwise you can import a library into your application in the traditional way through your IDE.

Coding First Steps - Launching CoPilot

Note: Below are a few high-level explanations based on the sample application provided.

Reference files: SDKApp.java

String cpPackageName = "com.alk.copilot";
Intent coPilotIntent = new Intent(Intent.ACTION_MAIN);
coPilotIntent.setClassName(cpPackageName, "com.alk.copilot.Copilot");
try{
    startActivity(coPilotIntent);
}
catch(Exception e)
{
    coPilotIntent.setClassName(cpPackageName, "com.alk.copilot.CopilotActivity");
    startActivity(coPilotIntent);
}

The above code launches CoPilot using an intent, finding the package name and launching the activity. At this stage you can also change the minimize-button behavior in CoPilot so that when it’s pressed it returns to your app. Just put the following lines before running startActivity:

coPilotIntent.putExtra("SDK_CLIENT_PACKAGE_NAME", "com.alk.sdk"); coPilotIntent.putExtra("SDK_CLIENT_CLASS_NAME", "com.alk.sdk.SDKApp");

In the example above CoPilot will go back into the sample application when the minimize button is pressed. Change the package and class name to suit your application.

Coding First steps - Connecting to CoPilot

Note: Below are a few high-level explanations based on the sample application provided.

Reference files: SDKApp.java

Before any APIs can be used with CoPilot a connection must be established first. Remember the INTERNET permission must be enabled for your application in order to communicate over the localhost sockets.

//Load the SDK and attempt to make a connection
try {
    System.loadLibrary("alksdk");
} catch (UnsatisfiedLinkError ex) {
    Log.v("CPCON","Shared Library Failed to Load.");
    return;
}
if (AlkMsg.Msg_StartUp("OnConnectionEvent",  null, true, true, true, 0, this) <=0) {
    Log.v("CPCON", "Call to Msg_StartUp() Failed.");
    return;
}

The above attempts to load the SDK and then start the messaging with CoPilot. If you trigger the UnsatisfiedLinkError exception as above then it is likely your application is not referencing the libalksdk.so file mentioned previously and you should check your dependencies.

The first parameter in AlkMsg.Msg_Startup() is the call back function that will be called when connection statuses are available. For example:

public void OnConnectionEvent(int event, int connectionID)
{
    AlkMsg.ConnEventType connectionStatus = AlkMsg.ConnEventType.values()[event];
    Log.v("CPCON", "OnConnectionEvent: " + connectionStatus);
    if(connectionStatus == AlkMsg.ConnEventType.CET_Connected) {
// We are connected, we can talk to CoPilot now
    }
}

Coding First steps - Licensing CoPilot

Note: Below are a few high-level explanations based on the sample application provided.

Reference files: License.java

In order to use and work with your build of CoPilot it first needs to be activated. This is done using our License APIs. I’ve provided you with two keys a base region key and a truck upgrade key. The region key should always be activated first and any upgrade keys should follow after. Activating a license is done with Msg_ActivateLicense(), for example:

AlkMsg.Msg_UpdateOptions(AlkMsg.MSG_ID_LicenseResponse, true, false, "OnLicenseResponse", 0, this );

AlkMsg.Msg_ActivateLicense("XXXX-XXXX-XXXX-XXXX", AlkMsg.EActivationOptions.ACTIVATE_OPT_RESET_OFFLINE.getValue());

The first line registers a call back (more details below) this is called whenever the licensing API has a response for the calling application. The second line actually tells CoPilot to activate the license. Upon success CoPilot will then be able to use North America maps.

Note: You may have been provided with multiple keys for activation

CoPilot Region License Key Should always be activated first. This key licenses CoPilot for navigation and SDK access in the MAP REGION Region.

CoPilot Truck Upgrade Key This upgrade licenses CoPilot to use truck routing and the related routing profiles.

CoPilot ActiveTraffic Upgrade Key This upgrade licenses CoPilot to use ActiveTraffic within CoPilot.

public void OnLicenseResponse(long buffer, int len)
{
    int[] response= new int[1];
    int[] status=new int[1];
    AlkMsg.Msg_GetLicenseNotification(buffer, len, response, status);
    try{
        Log.v("CPLic", "Response:" +  Integer.toString(response[0])  + "\n" +
                "Status:" +  Integer.toString(status[0]));
        if(status[0] == LIC_SUCCESS) {
            // The license was successful. You can now activate the next license or do something else
        }
    }catch(Exception e) {}
}

The above is the callback function that was registered earlier, prior to activation. All responses from the licensing module will be passed here. In the code above we’re checking for a successful activation and if there is one we can continue the workflow (either activate the next license or something else your app would need to do).

Coding First Steps

Following the above means you should now have a basic controlling application that is able to Launch CoPilot, connect to the SDK and then license it using your key - all through the code.

The next steps are up to you. Most projects now try to add destinations into CoPilot, there’s an example of this in our sample application - see AddressEntry.java in the source.