Android and Veery Service interraction overview

This section describes the overall architecture of the Veery SDK (including the Veery Agent) inside an android application.

Veery Architecture Android

Veery uses Firebase Cloud Messaging (FCM) to receive matching events. These events could either be visible to the user (if you decided so) or stay quiet in the background.

This helps the Veery Cache to stay updated with the last information that may be required by the application.

Therefore the Veery SDK can be called easily and quickly as all calls will be synchronous (without the need of having the network connected at the time of the call).

As most Predictions and Matchings are made hours before the actual event, the application can use them any time required.

Veery also offers callback mechanisms for the app to quickly react when a Prediction or a Matching occurs.

As these callbacks may be prevented of any visible messages to the user (when the user is not using your app at that time), Veery can also show a push notification to the user.

In that case, the visible content (envelope) of the notification will have to be mentioned at the time your app subscribes to an event (like a trip Prediction).

As a result Veery helps you to create out-app Notifications without the need of a Notification server, as everything about the notification is configured by the app developper itself.

Partial singleton pattern

The Veery class can be implemented as many time as required (usually once per activity using Veery).

The Veery Agent and the Veery Cache will be common (shared) between all instance of the class.

  • Some functions calls will have impact on the Agent or the Cache (and therefore will impact all Veery Objects).
  • Some functions will have impacts only on the local object.

Minimal communication required between the app and Veery

This is described in the android quick start page. So if you already performed the minimal integration the following information is presented just for your undestanding:

Veery(Context context)

Constructor of a Veery object.

serviceConnect()

Connect an activity to the Veery Agent. This should be called from the onCreate callback of the Activity object.

serviceDisconnect()

Disconnect an activity from the Veery Agent. This should be called from the onDestroy callback of the Activity object.

serviceResume()

Let the agent know that an activity has showed up to the user. This will have affect of activating the foreground mode of Veery, which turns the location service to a higher precision and refresh frequency.

This should be called from the onResume callback of the Activity object.

servicePause()

Let the agent know that an activity is about to be removed from user screen. This will have affect of activating the background mode of Veery (except if another activity has called serviceResume()).

It turns the location service either off, either to a lower consumption mode.

This should be called from the onPause callback of the Activity object.

setApiKeySecret(String apiKeySecret)

Set the Secret (password) attached to your API Key.

This is necessary to enable to use the backend based functions of Veery (Predictions, POI, Trips, Matchings, ...).

This should be called any time after the very first serviceConnect() is called (Usually on the onCreate callback of the main activity), before any other calls to any other function of Veery.

This function scopes the agent, so it is not necessary to call it from all Activities but only from the Main Activity.

setFirebaseToken(String token)

Let Veery know what is the FCM token of the device.

This should be called any time after FirebaseApp.initializeApp is called (Usually on the onCreate callback of the main activity).

It should also be called from the FirebaseInstanceIdService.onTokenRefresh() to let Veery know the token has changed

This function scopes the agent, so it is not necessary to call it from all Activities.

firebaseMessageHandler(RemoteMessage remoteMessage)

Transfers the FCM notifications to Veery.

The FCM notifications that are supposed to be handled by Veery will have specific signature, so only messages for Veery will be handled by Veery.

This should be called from the handler FirebaseMessagingService.onMessageReceived(RemoteMessage remoteMessage)

activate(int mode)

Turn the Veery agent into the geolocation mode required by your application (foreground, background, geo-predictive, ...).

It will request the necessary authorization from the user through the Android dialogs:

Veery auth

getStatus()

Allow to you to see :

  • If veery integration is successfully.
  • If the minimum required to use veery is completed.
  • If the connection to veery backend established.
  • Date of last positions sent to veery backend.
  • If APNs Token sent to veery background.
  • Date of last notification received from veery.