Skip to content

Getting Started

How to implement the Food SDK

The following sections cover how you can get started using Food functionality. You can easily integrate the Food Service by following these steps.

1. Dependencies

Open the main build.gradle file of your project and add the following dependencies:

1
2
3
4
5
6
7
dependencies {

    implementation 'com.telenav.commerce:foodservice:${version}'

    implementation 'com.telenav.commerce:common:${version}'

}

2. Initialization of the Food Service

The entry point to the Commerce Food Service is the IFoodApi which exposes the APIs needed for getting food specific information.

IFoodApi is exposed to the client by the implementation of IFoodUserServiceProvider → FoodManagerProvider.

IFoodApi

The interface exposes the APIs needed for getting food specific information.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
interface IFoodApi {

    @Throws(InitException::class)
    fun init(
        apiEndpoint: ApiEndpoint = ApiEndpoint.PRODUCTION,
        apiKey: String,
        apiKeySecret: String,
        userServiceProvider: IFoodUserServiceProvider,
        paymentProvider: IFoodPaymentServiceProvider
    )

    @WorkerThread
    suspend fun getBrands(): CommerceResponse<List<Brand>>

    @WorkerThread
    suspend fun getFoodStores(
        location: GeoLocation,
        brandId: String
    ): CommerceResponse<List<FoodStore>>

    @WorkerThread
    suspend fun getFoodStoresAlongRoute(
        location: GeoLocation,
        brandId: String,
        merchantKey: String,
        routePoints: List<GeoLocation>
    ): CommerceResponse<List<FoodStore>>


    @WorkerThread
    suspend fun getHistory(onlyActive: Boolean): CommerceResponse<List<FoodOrderInformation>>

This method initializes or updates the food service. Before interacting with food service, the client is responsible to call this method. In case of a switch to a different environment is desired, the method can be called again with the new endpoint and corresponding api keys and tokens.

The apiEndpoint parameter denotes the Commerce Service environment that we will use.

The default value points to ApiEndpoint.PRODUCTION.

The apiKey represents the unique key used by each integration client in order to use food module functionality.

The apiKeySecret parameter represents the unique key used by each integration client in order to use food module functionality together with apiKey.

The userServiceProvider parameter represents the user dependency required by food service for proper running. View the IFoodUserServiceProvider.

The paymentProvider parameter represents the user dependency required by food service for proper running. View the IFoodPaymentServiceProvider.

It throws com.telenav.commerce.models.network.InitException if called with empty apiKey and apiKeySecret. 

1
2
3
4
5
6
7
8
    @Throws(InitException::class)
    fun init(
        apiEndpoint: ApiEndpoint = ApiEndpoint.PRODUCTION,
        apiKey: String,
        apiKeySecret: String,
        userServiceProvider: IFoodUserServiceProvider,
        paymentProvider: IFoodPaymentServiceProvider
    )


The getBrands method returns a list of available food brands. If there are no available brands, then it returns an empty list.

1
2
@WorkerThread
    suspend fun getBrands(): CommerceResponse<List<Brand>>


The getFoodStores method makes a search based on the given location and brand and returns a list of FoodStore. The maximum of retrieve results is 9.

The location parameter represents the location for which the search is done.

The brandId parameter represents the id of the Brand for which the search is done.

It returns the list of the avalilable FoodStore. If there are no food stores available, then it returns an empty list.

1
2
3
4
5
@WorkerThread
    suspend fun getFoodStores(
        location: GeoLocation,
        brandId: String
    ): CommerceResponse<List<FoodStore>>


The getFoodStoresAlongRoute method returns a list of available food stores around the given location, along the provided route, and for the given brand. The results have the first one set as the default store.

The location parameter represents the coordinates around which the search should be done.

The brandId parameter represents the id of the Brand for which the search is done.

The routePoints parameter provides the list of route GeoLocation objects representing the route points.

It returns the list of the available FoodStore. If there are no food stores available, then it returns an empty list.

1
2
3
4
5
6
7
 @WorkerThread
    suspend fun getFoodStoresAlongRoute(
        location: GeoLocation,
        brandId: String,
        merchantKey: String,
        routePoints: List<GeoLocation>
    ): CommerceResponse<List<FoodStore>>


The getHistory method retrieves user's food orders.

The onlyActive parameter sets if request should return only active orders.

It returns a list of FoodOrderInformation representing the orders placed by an user.

1
2
@WorkerThread
    suspend fun getHistory(onlyActive: Boolean): CommerceResponse<List<FoodOrderInformation>>

IFoodUserServiceProvider

This interface is used for exposing an implementation of the API that is used by the client for accessing the food module functionality.

1
2
3
interface IFoodUserServiceProvider {
    fun getUserToken(): String
}


The getUserToken method retrieves the user token.

1
fun getUserToken(): String

Here is the code on how to initialize food service using the FoodManagerProvider:

1
2
3
4
5
6
7
FoodManagerProvider.provide().init(
            Utils.defaultEndpoint,
            BuildConfig.API_KEY,
            BuildConfig.API_SECRET,
            object : IFoodUserServiceProvider {},
            object : IFoodPaymentServiceProvider {}
)

Implementation example of IFoodUserServiceProvider

In order to implement the IFoodUserServiceProvider, use the following code.

1
2
3
4
5
 object : IFoodUserServiceProvider {
          override fun getUserToken(): String {
                 return userServiceProvider.getUserToken()
                 }
          }

2.2 Initialization of the Food Service with a IFoodCommerceApi provided by the client

If the client needs a specific SDK (network) configuration, then they can initialize the food service passing their own instance of IFoodCommerceApi.

1
2
3
4
5
6
7
FoodManagerProvider.provide(foodApiManager).init(
             apiEndpoint,
             apiKey,
             apiKeySecret,
             object : IFoodUserServiceProvider {},
            object : IFoodPaymentServiceProvider {}
)

IFoodCommerceApi

This interface represents the entry point to Commerce Service in regards of food flow. It exposes APIs needed for getting food specific information.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
interface IFoodCommerceApi {

    fun setConfiguration(configuration: SdkConfiguration)

    suspend fun getBrands(): CommerceResponse<List<Brand>>

    suspend fun getFoodStoresAlongRoute(
        location: GeoLocation,
        brandId: String,
        routePoints: List<GeoLocation>
    ): CommerceResponse<List<FoodStore>>

    suspend fun getDefaultStore(
        location: GeoLocation,
        brandId: String,
        merchantKey: String,
        routePoints: List<GeoLocation>
    ): CommerceResponse<FoodStore?>

    suspend fun getFoodStores(
        location: GeoLocation,
        brandId: String
    ): CommerceResponse<List<FoodStore>>

    suspend fun getFoodHistory(onlyActive: Boolean): CommerceResponse<List<FoodOrderInformation>>
}


The setConfiguration method updates the IHttpApi instance with the given configuration to be used in the communication with commerce service.

1
fun setConfiguration(configuration: SdkConfiguration)


The getBrands method returns a list of available food brands. If there are no available brands, then it returns an empty list.

1
suspend fun getBrands(): CommerceResponse<List<Brand>>


The getFoodStoresAlongRoute method returns a list of available food stores around the given location, along the provided route, and for the given brand.

The location parameter provides the coordinates around which the search should be done.

The brandId parameter represents the id of the Brand for which the search should be done.

The routePoints parameter represents the list of route GeoLocation objects representing the route points.

1
2
3
4
5
 suspend fun getFoodStoresAlongRoute(
        location: GeoLocation,
        brandId: String,
        routePoints: List<GeoLocation>
    ): CommerceResponse<List<FoodStore>>


The getDefaultStore method returns a store that matches the default store algorithm described below:

  • If there is no previous order history with the merchant(brand)
    • If Free Drive:
      • If there is a store within 'food search radius' and store if open -> Select nearest store.
    • If Active Navigation:
      • If there is a store within 'X' minutes (X <= 10) of detour time from current route; store is open.
      • Driving time from CVP and store is less than 'Y' mins (Y = 60) -> select the store that is closest (driving time) to the user and has a detour of less X mins
  • If there is previous order history with the merchant:
    • If Free Drive:
      • select the nearest open store from all available order history within 'search radius'
      • if no order history store is open and available within the search radius -> select the nearest open store
    • If Active Navigation:
      • use the same logic as no order history.

The location parameter represents the coordinates around which the search is done.

The brandId parameter represents the id of the Brand for which the search is done.

The routePoints parameter represents the list of route GeoLocation objects representing the route points.

1
2
3
4
5
6
    suspend fun getDefaultStore(
        location: GeoLocation,
        brandId: String,
        merchantKey: String,
        routePoints: List<GeoLocation>
    ): CommerceResponse<FoodStore?>


The getFoodStores method returns a list of available food stores around the given location and for the given brand.

The location parameter represents the coordinates around which the search should be done.

The brandId parameter represents the id of the Brand for which the search is done.

1
2
3
4
    suspend fun getFoodStores(
        location: GeoLocation,
        brandId: String
    ): CommerceResponse<List<FoodStore>>


The getFoodHistory method retrieves user's food orders.

The onlyActive parameter sets if request should return only active items.

It returns a list of FoodOrderInformation representing the orders placed by an user.

1
    suspend fun getFoodHistory(onlyActive: Boolean): CommerceResponse<List<FoodOrderInformation>>