Init API

Overview

Init API provides initialization functions for gaining access to Navigation module as well as high-level control functions.

Please note that initialization process using the functions in this chapter only applies to standalone integration type. Embedded integration does not require initalization phase as it is done automatically when placing navigation into a frame.

This API contains functions, which set up or close down connection such as Init, Connect and Disconnect, functions, which start up Navigation module such as Show and EndApplication, monitoring whether navigation is running, exit or in background through IsApplicationRunning and IsApplicationInForeground.
There are supporting functions, which allows you to put navigation into foreground or background such as BringApplicationToBackground and Show.

Important is the support for a management of callback functionality using RegisterCallback and UnregisterCallback so that important events from navigation can be captured by an integrating application and react on it.

Initialization flow for Standalone Integration

It is important to follow the correct initilization flow so that one avoids receiving undesired exceptions when calling API functions.
There are problematic situations that the Navigation API service is not connected yet and you call API functions, or you call the function like NavigateToAddress while Sygic navigation has not been started yet.

In order to avoid such problems please consider this recommended control flow

1. Call Api.init()
2. Call Api.connect()
3. Wait for the onServiceConnected()callback is triggered before doing any API function calls
4. Check whether the navigation is running using the isApplicationRunning() function
5. If not, call Api.show() and then wait for EVENT_APP_STARTED within the OnEvent() function
6. Now the navigation is running and you can call any API functions
7. If the navigation is terminated EVENT_APP_EXIT is generated. For API to work again you should restart with the step 4.
8. If Sygic Navigation crashes the onServiceDisconnected() callback is triggered and you need to start again from the step 2.

In the following table see the result of API calls at three different states of "connection"

Please check Getting Started with Standalone Integration for the guidelines and full sample reference.

Initialization flow for Embedded Integration

As already mentioned the initialization flow for Embedded integration does not need a use of the functions Init/Connect/Disconnect/Show/RegisterCallback, but it is all done behind the fragment initialization.
Please check Getting Started with Embedded Integration for the guidelines and full sample reference.

Attention
However it is important to note that the initialization flow takes few milliseconds.
It means that an unexpected crash can occur in case an API call is used immediately at the start, e.g. in early stages of OnCreate() function.
Therefore it is recommended to make sure an API call is not used before the event ApiEvents.EVENT_APP_STARTED occurs (see SygicNaviCallback).

Init/Connect

Init is the decisive operation in the standalone integration, which defines which version of navigation is used. The Init function should be immediately followed by the call of Connect, which sets up the communication channel to navigation.

Example

This sample demonstrates how to open Sygic navigation. They key point here is the parameter set in the API function Init.
Here we demonstrate binding to Sygic Professional navigation engine, which is represented by the 2nd and 3rd parameters. For other types of navigation you need to change the two parameters as follows.
For Sygic Professional you need to set the parameters to com.sygic.fleet and Api.CLASS_FLEET.
For Sygic Truck you need to set the parameters to com.sygic.truck and Api.CLASS_TRUCK.
For 2D version of navigation called Sygic Drive you need to set the parameters to com.sygic.drive and Api.CLASS_DRIVE.

Please note Sygic Truck will cease to be API supported in future (estimated end of year 2018). Its replacement is Sygic Professional which encompasses car, truck, van, camper alternatives.

    import com.sygic.sdk.remoteapi.Api;
    ...
    private Api mApi;
    private ApiCallback = null;
    ...
    mApi = Api.init(getApplicationContext(), "com.sygic.fleet", Api.CLASS_FLEET, mCallback);
    mApi.connect();

IsApplicationRunning

This functions detects whether Navigation application si running or not. This detection only gives relevant information when API is connected. Otherwise the call returns an exception.
Check details of IsApplicationRunning in the reference manual.

Example

This example enables the hypothetical application button btnNavigate only in case that Sygic navigation application is running and API channel is set up.

Button btnNavigate = (Button)findViewById(R.id.btnNavigate);
try {
   boolean isRun = Api.isApplicationRunning(0);
   if (isRun)
   {
      btnNavigate.setEnabled(true);
   }
   else
   {
      btnNavigate.setEnabled(false);
   }
} 
catch (GeneralException e)
{
   btnNavigate.setEnabled(false);
}

Show

The function starts Sygic navigation application if it is not yet open. In that case you may expect the event APP_STARTED in few moments, meaning navigation application is opening and when done the event is generated. However make sure you do not call API functions (such as NavigateToAddress, etc) in the meantime before the event is obtained, meaning before navigation is open. If the Sygic navigation was already open the API call generates no event and the API call basically does not nothing. However if the navigation was in a background and the argument of the call is false, the navigation will get into foreground.

Check details of Show in the reference manual.

Example

In this example we asume the hypothetical application button btnMap, through which we open Sygic navigation, or else put it into foreground.

mApi = Api.init(getApplicationContext(), "com.sygic.fleet", Api.CLASS_FLEET, mApiCallback);
mApi.connect();

Button btnMap = (Button)findViewById(R.id.btnMap);
btnMap.setOnClickListener(new View.OnClickListener() {
   public void onClick(View v)
   {
      try {
        mApi.show(false);
      } catch (RemoteException e) {
        e.printStackTrace();
      }
   }
});

Callback initialization

Majority of integrating applications want to capture navigation events so that they can react appropriately.
It is the ApiCallback class object, which enacapsulates all events coming from navigation module and API itself. The callback class istantiation is typically static and its reference is given to Init as an argument.

When API service is connected the OnServiceConnected method is called. This is the result of Connect call, but please note that callback method is not triggered in case the API service was already connected.
When API service is disconnected as a cause of OS decision or possible crash the OnServiceConnected method is called. Please note it is not called with an explict call of Disconnect function.
Finally the onEvent method is called with various navigation events such as EVENT_SPEED_EXCEEDING, passing the event details in its argument.

It is important to know that to enable onEvent callback the API needs to be registered using RegisterCallback. OnServiceConnected and OnServiceDisconnected are enabled automatically.

Example

This example shows a definition of the callback object ApiCallback and an intialization of API with the given callback.
The initialization is called, as typical in Android, with a start of application at the OnCreate method.

    private Api mApi;
    private ApiCallback mApiCallback = new ApiCallback() {

        @Override
        public void onServiceConnected() {
            try {
                mApi.registerCallback();
            } catch (RemoteException e) {
                e.printStackTrace();
            }        
        }

        @Override
        public void onServiceDisconnected() {
        }        

        @Override
        public void onEvent(int event, String data) {
        }
    };

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        mApi = Api.init(getApplicationContext(), "com.sygic.fleet", Api.CLASS_FLEET , mApiCallback);
        mApi.connect();
    }

Background/Foreground

To put Sygic into background we use the API function bringApplicationToBackground().
To put Sygic into foreground we use the API function show(). The function show also starts the navigation if it is not started.
In case it is started the function brings the navigation into foreground with the setting the parameter to false. Setting parameter to true should start the navigation to background, but this behavior is deprecated for Android.

Check details of BringApplicationToBackground in the reference manual.

Example

The example shows toggling the navigation to background and foreground based on the value of the variable fg.

    import com.sygic.sdk.remoteapi.Api;
    ...
    private boolean fg = true;
    ...
    try {
        if (fg == true)
        {
        mApi.show(false);
        }
        else
        {
        mApi.bringApplicationToBackground();
        }
    } catch (RemoteException e) {
        e.printStackTrace();
    }

Events

API Events allow monitoring of control events with a possibility to react on it.
The following events are available.

Check for more on Api Events in the reference manual.