CHXXX : Better docs (#55)

* Better docs

* Tweaks

* Updates

* Updates

* Updates

* Add user segments support and tests

* Fixes

Co-authored-by: cgee1 <[email protected]>

Author: rubikzube

library/src/main/java/io/constructor/core/Constants.kt

@@ -15,6 +15,7 @@ class Constants {
         const val SESSION = "s"
         const val TIMESTAMP = "_dt"
         const val IDENTITY = "i"
+        const val SEGMENTS = "us"
         const val ACTION = "action"
         const val AUTOCOMPLETE_SECTION = "autocomplete_section"
         const val ORIGINAL_QUERY = "original_query"

library/src/main/java/io/constructor/core/ConstructorIo.kt

@@ -7,7 +7,6 @@ import io.constructor.data.DataManager
 import io.constructor.data.local.PreferencesHelper
 import io.constructor.data.memory.ConfigMemoryHolder
 import io.constructor.data.model.autocomplete.AutocompleteResponse
-import io.constructor.data.model.common.Result
 import io.constructor.data.model.common.ResultGroup
 import io.constructor.data.model.search.SearchResponse
 import io.constructor.data.model.browse.BrowseResponse
@@ -35,6 +34,9 @@ object ConstructorIo {
     private lateinit var context: Context
     private var disposable = CompositeDisposable()
 
+    /**
+     *  Sets the logged in user identifier
+     */
     var userId: String?
         get() = configMemoryHolder.userId
         set(value) {
@@ -52,6 +54,11 @@ object ConstructorIo {
         trackSessionStart()
     }
 
+    /**
+     *  Initializes the client
+     *  @param context the context
+     *  @param constructorIoConfig the client configuration
+     */
     fun init(context: Context?, constructorIoConfig: ConstructorIoConfig) {
         if (context == null) {
             throw IllegalStateException("context is null, please init library using ConstructorIo.with(context)")
@@ -61,6 +68,7 @@ object ConstructorIo {
         configMemoryHolder = component.configMemoryHolder()
         configMemoryHolder.autocompleteResultCount = constructorIoConfig.autocompleteResultCount
         configMemoryHolder.testCellParams = constructorIoConfig.testCells
+        configMemoryHolder.segments = constructorIoConfig.segments
 
         preferenceHelper = component.preferenceHelper()
         preferenceHelper.apiKey = constructorIoConfig.apiKey
@@ -76,8 +84,14 @@ object ConstructorIo {
         dataManager = component.dataManager()
     }
 
+    /**
+     * Returns the current session identifier (an incrementing integer)
+     */
     fun getSessionId() = preferenceHelper.getSessionId()
 
+    /**
+     * Returns the current client identifier (a random GUID assigned to the app running on the device)
+     */
     fun getClientId() = preferenceHelper.id
 
     internal fun testInit(context: Context?, constructorIoConfig: ConstructorIoConfig, dataManager: DataManager, preferenceHelper: PreferencesHelper, configMemoryHolder: ConfigMemoryHolder) {
@@ -97,18 +111,25 @@ object ConstructorIo {
     /**
      * Returns a list of autocomplete suggestions
      */
-    fun getAutocompleteResults(query: String): Observable<ConstructorData<AutocompleteResponse>> {
+    fun getAutocompleteResults(term: String): Observable<ConstructorData<AutocompleteResponse>> {
         val params = mutableListOf<Pair<String, String>>()
         configMemoryHolder.autocompleteResultCount?.entries?.forEach {
             params.add(Pair(Constants.QueryConstants.NUM_RESULTS+it.key, it.value.toString()))
         }
-        return dataManager.getAutocompleteResults(query, params.toTypedArray())
+        return dataManager.getAutocompleteResults(term, params.toTypedArray())
     }
 
     /**
-     * Returns search results including filters, categories, sort options, etc.
+     * Returns a list of search results including filters, categories, sort options, etc.
+     * @param term the term to search for
+     * @param facets  additional facets used to refine results
+     * @param page the page number of the results
+     * @param perPage The number of results per page to return
+     * @param groupId category facet used to refine results
+     * @param sortBy the sort method for results
+     * @param sortOrder the sort order for results
      */
-    fun getSearchResults(text: String, facets: List<Pair<String, List<String>>>? = null, page: Int? = null, perPage: Int? = null, groupId: Int? = null, sortBy: String? = null, sortOrder: String? = null): Observable<ConstructorData<SearchResponse>> {
+    fun getSearchResults(term: String, facets: List<Pair<String, List<String>>>? = null, page: Int? = null, perPage: Int? = null, groupId: Int? = null, sortBy: String? = null, sortOrder: String? = null): Observable<ConstructorData<SearchResponse>> {
         val encodedParams: ArrayList<Pair<String, String>> = arrayListOf()
         groupId?.let { encodedParams.add(Constants.QueryConstants.FILTER_GROUP_ID.urlEncode() to it.toString()) }
         page?.let { encodedParams.add(Constants.QueryConstants.PAGE.urlEncode() to page.toString().urlEncode()) }
@@ -120,7 +141,33 @@ object ConstructorIo {
                 encodedParams.add(Constants.QueryConstants.FILTER_FACET.format(facet.first).urlEncode() to it.urlEncode())
             }
         }
-        return dataManager.getSearchResults(text, encodedParams = encodedParams.toTypedArray())
+        return dataManager.getSearchResults(term, encodedParams = encodedParams.toTypedArray())
+    }
+
+    /**
+     * Returns a list of browse results including filters, categories, sort options, etc.
+     * @param filterName filter name to display results from
+     * @param filterValue filter value to display results from
+     * @param facets  additional facets used to refine results
+     * @param page the page number of the results
+     * @param perPage The number of results per page to return
+     * @param groupId category facet used to refine results
+     * @param sortBy the sort method for results
+     * @param sortOrder the sort order for results
+     */
+    fun getBrowseResults(filterName: String, filterValue: String, facets: List<Pair<String, List<String>>>? = null, page: Int? = null, perPage: Int? = null, groupId: Int? = null, sortBy: String? = null, sortOrder: String? = null): Observable<ConstructorData<BrowseResponse>> {
+        val encodedParams: ArrayList<Pair<String, String>> = arrayListOf()
+        groupId?.let { encodedParams.add(Constants.QueryConstants.FILTER_GROUP_ID.urlEncode() to it.toString()) }
+        page?.let { encodedParams.add(Constants.QueryConstants.PAGE.urlEncode() to page.toString().urlEncode()) }
+        perPage?.let { encodedParams.add(Constants.QueryConstants.PER_PAGE.urlEncode() to perPage.toString().urlEncode()) }
+        sortBy?.let { encodedParams.add(Constants.QueryConstants.SORT_BY.urlEncode() to it.urlEncode()) }
+        sortOrder?.let { encodedParams.add(Constants.QueryConstants.SORT_ORDER.urlEncode() to it.urlEncode()) }
+        facets?.forEach { facet ->
+            facet.second.forEach {
+                encodedParams.add(Constants.QueryConstants.FILTER_FACET.format(facet.first).urlEncode() to it.urlEncode())
+            }
+        }
+        return dataManager.getBrowseResults(filterName, filterValue, encodedParams = encodedParams.toTypedArray())
     }
 
     /**
@@ -140,6 +187,7 @@ object ConstructorIo {
 
     /**
      * Tracks input focus events
+     * @param term the term currently in the search bar
      */
     fun trackInputFocus(term: String?) {
         var completable = trackInputFocusInternal(term)
@@ -156,6 +204,11 @@ object ConstructorIo {
 
     /**
      * Tracks autocomplete select events
+     * @param searchTerm the term selected, i.e. "Pumpkin"
+     * @param originalQuery the term in the search bar, i.e. "Pum"
+     * @param sectionName the section the selection came from, i.e. "Search Suggestions"
+     * @param resultGroup the group to search within if a user selected to search in a group, i.e. "Pumpkin in Canned Goods"
+     * @param resultID the result ID of the autocomplete response that the selection came from
      */
     fun trackAutocompleteSelect(searchTerm: String, originalQuery: String, sectionName: String, resultGroup: ResultGroup? = null, resultID: String? = null) {
         var completable = trackAutocompleteSelectInternal(searchTerm, originalQuery, sectionName, resultGroup, resultID);
@@ -180,7 +233,10 @@ object ConstructorIo {
 
     /**
      * Tracks search submit events
-     */
+     * @param searchTerm the term selected, i.e. "Pumpkin"
+     * @param originalQuery the term in the search bar, i.e. "Pum"
+     * @param resultGroup the group to search within if a user elected to search in a group, i.e. "Pumpkin in Canned Goods"
+    */
     fun trackSearchSubmit(searchTerm: String, originalQuery: String, resultGroup: ResultGroup?) {
         var completable = trackSearchSubmitInternal(searchTerm, originalQuery, resultGroup)
         disposable.add(completable.subscribeOn(Schedulers.io()).subscribe({
@@ -202,6 +258,8 @@ object ConstructorIo {
 
     /**
      * Tracks search results loaded (a.k.a. search results viewed) events
+     * @param term the term that results are displayed for, i.e. "Pumpkin"
+     * @param resultCount the number of results for that term
      */
     fun trackSearchResultsLoaded(term: String, resultCount: Int) {
         var completable = trackSearchResultsLoadedInternal(term, resultCount)
@@ -218,7 +276,12 @@ object ConstructorIo {
 
     /**
      * Tracks search result click events
-     */
+     * @param itemName the name of the clicked item i.e. "Kabocha Pumpkin"
+     * @param customerId the identifier of the clicked item i.e "PUMP-KAB-0002"
+     * @param searchTerm the term that results are displayed for, i.e. "Pumpkin"
+     * @param sectionName the section that the results came from, i.e. "Products"
+     * @param resultID the result ID of the search response that the click came from
+    */
     fun trackSearchResultClick(itemName: String, customerId: String, searchTerm: String = Constants.QueryConstants.TERM_UNKNOWN, sectionName: String? = null, resultID: String? = null) {
         var completable = trackSearchResultClickInternal(itemName, customerId, searchTerm, sectionName, resultID)
         disposable.add(completable.subscribeOn(Schedulers.io()).subscribe({}, {
@@ -238,6 +301,10 @@ object ConstructorIo {
 
     /**
      * Tracks conversion (a.k.a add to cart) events
+     * @param itemName the name of the converting item i.e. "Kabocha Pumpkin"
+     * @param customerId the identifier of the converting item i.e "PUMP-KAB-0002"
+     * @param searchTerm the search term that lead to the event (if adding to cart in a search flow)
+     * @param sectionName the section that the results came from, i.e. "Products"
      */
     fun trackConversion(itemName: String, customerId: String, revenue: Double?, searchTerm: String = Constants.QueryConstants.TERM_UNKNOWN, sectionName: String? = null) {
         var completable = trackConversionInternal(itemName, customerId, revenue, searchTerm, sectionName)
@@ -255,41 +322,29 @@ object ConstructorIo {
 
     /**
      * Tracks purchase events
-     */
-    fun trackPurchase(clientIds: Array<String>, revenue: Double?, orderID: String, sectionName: String? = null) {
-        var completable = trackPurchaseInternal(clientIds, revenue, orderID, sectionName)
+     * @param customerIds the identifiers of the purchased items
+     * @param revenue the revenue of the purchase event
+     * @param orderID the identifier of the order
+    */
+    fun trackPurchase(customerIds: Array<String>, revenue: Double?, orderID: String, sectionName: String? = null) {
+        var completable = trackPurchaseInternal(customerIds, revenue, orderID, sectionName)
         disposable.add(completable.subscribeOn(Schedulers.io()).subscribe({}, {
             t -> e("Purchase error: ${t.message}")
         }))
     }
-    internal fun trackPurchaseInternal(clientIds: Array<String>, revenue: Double?, orderID: String, sectionName: String? = null): Completable {
+    internal fun trackPurchaseInternal(customerIds: Array<String>, revenue: Double?, orderID: String, sectionName: String? = null): Completable {
         preferenceHelper.getSessionId(sessionIncrementHandler)
         val sectionNameParam = sectionName ?: preferenceHelper.defaultItemSection
         val revenueString = revenue?.let { "%.2f".format(revenue) }
         val params = mutableListOf(Constants.QueryConstants.AUTOCOMPLETE_SECTION to sectionNameParam)
-        return dataManager.trackPurchase(clientIds.toList(), revenueString, orderID, params.toTypedArray())
-    }
-
-    /**
-     * Returns browse results including filters, categories, sort options, etc.
-     */
-    fun getBrowseResults(filterName: String, filterValue: String, facets: List<Pair<String, List<String>>>? = null, page: Int? = null, perPage: Int? = null, groupId: Int? = null, sortBy: String? = null, sortOrder: String? = null): Observable<ConstructorData<BrowseResponse>> {
-        val encodedParams: ArrayList<Pair<String, String>> = arrayListOf()
-        groupId?.let { encodedParams.add(Constants.QueryConstants.FILTER_GROUP_ID.urlEncode() to it.toString()) }
-        page?.let { encodedParams.add(Constants.QueryConstants.PAGE.urlEncode() to page.toString().urlEncode()) }
-        perPage?.let { encodedParams.add(Constants.QueryConstants.PER_PAGE.urlEncode() to perPage.toString().urlEncode()) }
-        sortBy?.let { encodedParams.add(Constants.QueryConstants.SORT_BY.urlEncode() to it.urlEncode()) }
-        sortOrder?.let { encodedParams.add(Constants.QueryConstants.SORT_ORDER.urlEncode() to it.urlEncode()) }
-        facets?.forEach { facet ->
-            facet.second.forEach {
-                encodedParams.add(Constants.QueryConstants.FILTER_FACET.format(facet.first).urlEncode() to it.urlEncode())
-            }
-        }
-        return dataManager.getBrowseResults(filterName, filterValue, encodedParams = encodedParams.toTypedArray())
+        return dataManager.trackPurchase(customerIds.toList(), revenueString, orderID, params.toTypedArray())
     }
 
     /**
-     * Tracks browse results loaded (a.k.a. browse results viewed) events
+     * Tracks browse result loaded (a.k.a. browse results viewed) events
+     * @param filterName the name of the primary filter, i.e. "Aisle"
+     * @param filterValue the value of the primary filter, i.e. "Produce"
+     * @param resultCount the number of results for that filter name/value pair
      */
     fun trackBrowseResultsLoaded(filterName: String, filterValue: String, resultCount: Int) {
         var completable = trackBrowseResultsLoadedInternal(filterName, filterValue, resultCount)
@@ -306,6 +361,11 @@ object ConstructorIo {
 
     /**
      * Tracks browse result click events
+     * @param filterName the name of the primary filter, i.e. "Aisle"
+     * @param filterValue the value of the primary filter, i.e. "Produce"
+     * @param customerId the item identifier of the clicked item i.e "PUMP-KAB-0002"
+     * @param sectionName the section that the results came from, i.e. "Products"
+     * @param resultID the result ID of the browse response that the selection came from
      */
     fun trackBrowseResultClick(filterName: String, filterValue: String, customerId: String, resultPositionOnPage: Int, sectionName: String? = null, resultID: String? = null) {
         var completable = trackBrowseResultClickInternal(filterName, filterValue, customerId, resultPositionOnPage, sectionName, resultID)

library/src/main/java/io/constructor/core/ConstructorIoConfig.kt

@@ -2,10 +2,24 @@ package io.constructor.core
 
 import io.constructor.BuildConfig
 
-data class ConstructorIoConfig(val apiKey: String,
-                               val serviceUrl: String = BuildConfig.SERVICE_URL,
-                               val autocompleteResultCount: Map<String, Int> = mapOf(Constants.QueryValues.SEARCH_SUGGESTIONS to 10, Constants.QueryValues.PRODUCTS to 0),
-                               val defaultItemSection: String = BuildConfig.DEFAULT_ITEM_SECTION,
-                               val testCells: List<Pair<String, String>> = emptyList(),
-                               val servicePort: Int = BuildConfig.SERVICE_PORT,
-                               val serviceScheme: String = BuildConfig.SERVICE_SCHEME)
+/**
+ *  Used to configure the Constructor SDK client
+ *  @property apiKey Constructor.io API key
+ *  @property serviceUrl Constructor.io service URL (defaults to "ac.cnstrc.com")
+ *  @property autocompleteResultCount The number of results to return per section when requesting autocomplete results
+ *  @property defaultItemSection The item section when requesting data and sending tracking events (defaults to "Products")
+ *  @property segments Arbitrary customer defined user segments
+ *  @property testCells Test cell name/value pairs if A/B testing
+ *  @property servicePort The port to use (for testing purposes only, defaults to 443)
+ *  @property serviceScheme The scheme to use (for testing purposes only, defaults to HTTPS)
+ */
+data class ConstructorIoConfig(
+        val apiKey: String,
+        val serviceUrl: String = BuildConfig.SERVICE_URL,
+        val segments: List<String> = emptyList(),
+        val testCells: List<Pair<String, String>> = emptyList(),
+        val autocompleteResultCount: Map<String, Int> = mapOf(Constants.QueryValues.SEARCH_SUGGESTIONS to 10, Constants.QueryValues.PRODUCTS to 0),
+        val defaultItemSection: String = BuildConfig.DEFAULT_ITEM_SECTION,
+        val servicePort: Int = BuildConfig.SERVICE_PORT,
+        val serviceScheme: String = BuildConfig.SERVICE_SCHEME
+)

library/src/main/java/io/constructor/data/DataManager.kt

@@ -15,8 +15,8 @@ import javax.inject.Singleton
 class DataManager @Inject
 constructor(private val constructorApi: ConstructorApi, private val moshi: Moshi) {
 
-    fun getAutocompleteResults(text: String, params: Array<Pair<String, String>> = arrayOf()): Observable<ConstructorData<AutocompleteResponse>> {
-        return constructorApi.getAutocompleteResults(text, params.toMap()).map {
+    fun getAutocompleteResults(term: String, params: Array<Pair<String, String>> = arrayOf()): Observable<ConstructorData<AutocompleteResponse>> {
+        return constructorApi.getAutocompleteResults(term, params.toMap()).map {
             if (!it.isError) {
                 it.response()?.let {
                     if (it.isSuccessful) {
@@ -35,8 +35,8 @@ constructor(private val constructorApi: ConstructorApi, private val moshi: Moshi
         }.toObservable()
     }
 
-    fun getSearchResults(text: String, encodedParams: Array<Pair<String, String>> = arrayOf()): Observable<ConstructorData<SearchResponse>> {
-        var dynamicUrl = "/${ApiPaths.URL_SEARCH.format(text)}"
+    fun getSearchResults(term: String, encodedParams: Array<Pair<String, String>> = arrayOf()): Observable<ConstructorData<SearchResponse>> {
+        var dynamicUrl = "/${ApiPaths.URL_SEARCH.format(term)}"
         encodedParams.forEachIndexed { index, pair ->
             dynamicUrl += "${if (index != 0) "&" else "?" }${pair.first}=${pair.second}"
         }

library/src/main/java/io/constructor/data/interceptor/RequestInterceptor.kt

@@ -33,6 +33,12 @@ class RequestInterceptor(val context: Context, private val preferencesHelper: Pr
             }
         }
 
+        configMemoryHolder.segments.forEach {
+            it?.let {
+                builder.addQueryParameter(Constants.QueryConstants.SEGMENTS, it)
+            }
+        }
+
         builder.addQueryParameter(Constants.QueryConstants.CLIENT, BuildConfig.CLIENT_VERSION)
         builder.addQueryParameter(Constants.QueryConstants.TIMESTAMP, System.currentTimeMillis().toString())
 

library/src/main/java/io/constructor/data/memory/ConfigMemoryHolder.kt

@@ -32,6 +32,8 @@ class ConfigMemoryHolder @Inject constructor() {
             backingString = combined
         }
 
+    var segments: List<String?> = emptyList()
+
     var autocompleteResultCount: Map<String, Int>? = null
 
     var userId: String? = null

library/src/test/java/io/constructor/core/ConstructorIoAutocompleteTest.kt

@@ -45,6 +45,7 @@ class ConstructorIoAutocompleteTest {
         every { configMemoryHolder.autocompleteResultCount } returns null
         every { configMemoryHolder.userId } returns "player-one"
         every { configMemoryHolder.testCellParams } returns emptyList()
+        every { configMemoryHolder.segments } returns emptyList()
 
         val config = ConstructorIoConfig("dummyKey")
         val dataManager = createTestDataManager(preferencesHelper, configMemoryHolder, ctx)