Merge pull request #10 from Optable/witness-api

witness API implementation

Author: bmilekic

DemoApp/DemoAppKotlin/app/src/main/java/co/optable/androidsdkdemo/ui/GAMBanner/GAMBannerFragment.kt

@@ -13,6 +13,7 @@ import android.widget.TextView
 import androidx.fragment.app.Fragment
 import androidx.lifecycle.Observer
 import co.optable.android_sdk.OptableSDK
+import co.optable.android_sdk.OptableWitnessProperties
 import co.optable.androidsdkdemo.MainActivity
 import co.optable.androidsdkdemo.R
 import com.google.android.gms.ads.doubleclick.PublisherAdRequest
@@ -50,6 +51,21 @@ class GAMBannerFragment : Fragment() {
                 targetingDataView.setText(msg)
                 mPublisherAdView.loadAd(adRequest.build())
             })
+
+            MainActivity.OPTABLE!!
+                .witness(
+                    "GAMBannerFragment.loadAdButtonClicked",
+                    hashMapOf("exampleKey" to "exampleValue")
+                )
+                .observe(viewLifecycleOwner, Observer { result ->
+                var msg = targetingDataView.text.toString()
+                if (result.status == OptableSDK.Status.SUCCESS) {
+                    msg += "\n\nSuccess calling witness API to log loadAdButtonClicked event.\n"
+                } else {
+                    msg += "\n\nOptableSDK Error: ${result.message}\n"
+                }
+                targetingDataView.setText(msg)
+            })
         }
 
         return root

README.md

@@ -134,6 +134,33 @@ MainActivity.OPTABLE!!
 
 On success, the resulting key values are typically sent as part of a subsequent ad call. Therefore we recommend that you either call `targeting()` before each ad call, or in parallel periodically, caching the resulting key values which you then provide in ad calls.
 
+### Witness API
+
+To send real-time event data from the user's device to the sandbox for eventual audience assembly, you can call the witness API as follows:
+
+```kotlin
+import co.optable.android_sdk.OptableSDK
+import co.optable.android_sdk.OptableWitnessProperties
+import my.org.app.MainActivity
+import android.util.Log
+...
+MainActivity.OPTABLE!!
+    .witness("example.event.type", hashMapOf("example" to "value"))
+    .observe(viewLifecycleOwner, Observer { result ->
+        if (result.status == OptableSDK.Status.SUCCESS) {
+            Log.i("Witness API Success... ")
+        } else {
+            // result.status is OptableSDK.Status.ERROR
+            // result.message is the error message
+            Log.e("Witness API Error: ${result.message}")
+        }
+    })
+```
+
+The specified event type and properties are associated with the logged event and which can be used for matching during audience assembly.
+
+Note that event properties are of type `OptableWitnessProperties` which is an alias for `HashMap<String,String>`, and should consist only of string keyvalue pairs.
+
 ### Integrating GAM360
 
 We can further extend the above `targeting` example to show an integration with a [Google Ad Manager 360](https://admanager.google.com/home/) ad server account:

android_sdk/src/main/java/co/optable/android_sdk/OptableSDK.kt

@@ -25,11 +25,17 @@ import java.security.MessageDigest
 typealias OptableIdentifyInput = List<String>
 
 /*
- * Identify API usually just returns {}... Void would be better but that results in retrofit2
- * error when parsing response, even when the API responded successfully, since {} is technically
- * a HashMap:
+ * Witness API expects event properties:
+ */
+typealias OptableWitnessProperties = HashMap<String, String>
+
+/*
+ * Identify and Witness APIs usually just return {}... Void would be better but that results in
+ * retrofit2 error when parsing response, even when the API responded successfully, since {} is
+ * technically a HashMap:
  */
 typealias OptableIdentifyResponse = HashMap<Any,Any>
+typealias OptableWitnessResponse = HashMap<Any,Any>
 
 /*
  * Targeting API responds with a key-values dictionary on success:
@@ -192,6 +198,44 @@ class OptableSDK(context: Context, host: String, app: String, insecure: Boolean
         return liveData
     }
 
+    /*
+     *  witness(event, properties) calls the Optable Sandbox "witness" API in order to log a
+     *  specified 'event' (e.g., "app.screenView", "ui.buttonPressed"), with the specified keyvalue
+     *  OptableWitnessProperties 'properties', which can be subsequently used for audience assembly.
+     *
+     *  It is asynchronous, so the caller may call observe() on the returned LiveData and expect
+     *  an instance of Response<OptableWitnessResponse> in the result. Success can be checked by
+     *  comparing result.status to OptableSDK.Status.SUCCESS. Note that result.data!! will point
+     *  to an empty HashMap on success, and can therefore be ignored.
+     */
+    fun witness(event: String, properties: OptableWitnessProperties):
+            LiveData<Response<OptableWitnessResponse>> {
+        val liveData = MutableLiveData<Response<OptableWitnessResponse>>()
+        val client = this.client
+
+        GlobalScope.launch {
+            val response = client.Witness(event, properties)
+            when (response) {
+                is EdgeResponse.Success -> {
+                    liveData.postValue(Response.success(response.body))
+                }
+                is EdgeResponse.ApiError -> {
+                    liveData.postValue(Response.error(response.body))
+                }
+                is EdgeResponse.NetworkError -> {
+                    liveData.postValue(Response.error(
+                        Response.Error("NetworkError", "None")))
+                }
+                is EdgeResponse.UnknownError -> {
+                    liveData.postValue(Response.error(
+                        Response.Error("UnknownError", "None")))
+                }
+            }
+        }
+
+        return liveData
+    }
+
     companion object {
         /*
          * eid(email) is a helper that returns type-prefixed SHA256(downcase(email))

android_sdk/src/main/java/co/optable/android_sdk/core/Client.kt

@@ -88,6 +88,15 @@ class Client(private val config: Config, private val context: Context) {
         return edgeService!!.Targeting(this.config.app)
     }
 
+    suspend fun Witness(event: String, properties: OptableWitnessProperties):
+            EdgeResponse<OptableWitnessResponse, OptableSDK.Response.Error>
+    {
+        val evtBody = HashMap<String,Any>()
+        evtBody.put("event", event)
+        evtBody.put("properties", properties)
+        return edgeService!!.Witness(this.config.app, evtBody)
+    }
+
     fun hasGAID(): Boolean {
         return ((gaid != null) && (gaidLAT == false) && !TextUtils.isEmpty(gaid!!))
     }

android_sdk/src/main/java/co/optable/android_sdk/edge/EdgeService.kt

@@ -4,10 +4,7 @@
  */
 package co.optable.android_sdk.edge
 
-import co.optable.android_sdk.OptableIdentifyInput
-import co.optable.android_sdk.OptableIdentifyResponse
-import co.optable.android_sdk.OptableSDK
-import co.optable.android_sdk.OptableTargetingResponse
+import co.optable.android_sdk.*
 import retrofit2.http.Body
 import retrofit2.http.GET
 import retrofit2.http.POST
@@ -23,4 +20,9 @@ interface EdgeService {
     suspend fun Targeting(@Path("app") app: String):
             EdgeResponse<OptableTargetingResponse, OptableSDK.Response.Error>
 
+    @POST("/{app}/witness")
+    suspend fun Witness(@Path("app") app: String,
+                        @Body witnessBody: HashMap<String,Any>):
+            EdgeResponse<OptableWitnessResponse, OptableSDK.Response.Error>
+
 }