Merge pull request #9 from Optable/issue-8

Explicitly support an optional PPID in identify()

Author: bmilekic

DemoApp/DemoAppKotlin/app/build.gradle

@@ -15,6 +15,7 @@ android {
         minSdkVersion 16
         targetSdkVersion 29
 
+        // Here we get version code and version name from latest git release tags:
         versionCode versioning.getVersionCode()
         versionName versioning.getVersionName(false)
         archivesBaseName = "optable-android-sdk-demo-kotlin"

README.md

@@ -81,9 +81,10 @@ import android.util.Log
 
 val emailString = "some.email@address.com"
 val sendGoogleAdIDBoolean = true
+val ppid = "my-id-123"
 
 MainActivity.OPTABLE!!
-    .identify(emailString, sendGoogleAdIDBoolean)
+    .identify(emailString, sendGoogleAdIDBoolean, ppid)
     .observe(viewLifecycleOwner, Observer
     { result ->
         if (result.status == OptableSDK.Status.SUCCESS) {
@@ -96,7 +97,7 @@ MainActivity.OPTABLE!!
     })
 ```
 
-The SDK `identify()` method will asynchronously connect to the configured sandbox and send IDs for resolution. You can register an observer to understand successful completion or errors.
+The SDK `identify()` method will asynchronously connect to the configured sandbox and send IDs for resolution. The second (`sendGoogleAdIDBoolean`) and third (`ppid`) arguments to `identify()` are optional. You can register an observer to understand successful completion or errors.
 
 > :warning: **Client-Side Email Hashing**: The SDK will compute the SHA-256 hash of the Email address on the client-side and send the hashed value to the sandbox. The Email address is **not** sent by the device in plain text.
 

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

@@ -124,28 +124,33 @@ class OptableSDK(context: Context, host: String, app: String, insecure: Boolean
     }
 
     /*
-     *  identify(email, gaid?) calls the Optable Sandbox "identify" API, passing it the SHA-256 of
-     *  the caller-provided 'email' and, when specified via the 'gaid' Boolean, the Google
-     *  Advertising ID of the device.
+     *  identify(email, gaid?, ppid?) calls the Optable Sandbox "identify" API, passing it the
+     *  SHA-256 of the caller-provided 'email' and, when specified via the 'gaid' Boolean, the
+     *  Google Advertising ID of the device. If the 'ppid' String is specified, it will also be
+     *  sent for identity resolution.
      *
-     *  It is asynchronous, so the caller may call observe() on the returned LiveData and expect
+     *  The function is async, so the caller may call observe() on the returned LiveData and expect
      *  an instance of Response<OptableIdentifyResponse> 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 identify(email: String, gaid: Boolean? = false):
+    fun identify(email: String, gaid: Boolean? = false, ppid: String? = null):
             LiveData<Response<OptableIdentifyResponse>>
     {
         var idList: OptableIdentifyInput = listOf()
 
         if (!TextUtils.isEmpty(email) &&
             android.util.Patterns.EMAIL_ADDRESS.matcher(email).matches())
         {
-            idList += "e:" + Companion.eid(email)
+            idList += Companion.eid(email)
         }
 
         if (gaid!! && this.client.hasGAID()) {
-            idList += "g:" + this.client.GAID()
+            idList += Companion.gaid(this.client.GAID()!!)
+        }
+
+        if ((ppid != null) && (ppid.length > 0)) {
+            idList += Companion.cid(ppid)
         }
 
         return this.identify(idList)
@@ -189,12 +194,26 @@ class OptableSDK(context: Context, host: String, app: String, insecure: Boolean
 
     companion object {
         /*
-         * eid(email) is a helper that returns SHA256(downcase(email))
+         * eid(email) is a helper that returns type-prefixed SHA256(downcase(email))
          */
         fun eid(email: String): String {
-            return MessageDigest.getInstance("SHA-256")
+            return "e:" + MessageDigest.getInstance("SHA-256")
                 .digest(email.toLowerCase().trim().toByteArray())
                 .fold("", { str, it -> str + "%02x".format(it) })
         }
+
+        /*
+         * gaid(gaid) is a helper that returns the type-prefixed Google Advertising ID
+         */
+        fun gaid(gaid: String): String {
+            return "g:" + gaid.toLowerCase().trim()
+        }
+
+        /*
+         * cid(ppid) is a helper that returns custom type-prefixed origin-provided PPID
+         */
+        fun cid(ppid: String): String {
+            return "c:" + ppid.trim()
+        }
     }
 }

android_sdk/src/test/java/co/optable/android_sdk/OptableSDKUnitTest.kt

@@ -13,7 +13,7 @@ import org.junit.Assert.*
 class OptableSDKUnitTest {
     @Test
     fun eid_isCorrect() {
-        val expected = "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"
+        val expected = "e:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"
 
         assertEquals(expected, OptableSDK.eid("123"))
         assertEquals(expected, OptableSDK.eid(" 123"))
@@ -33,4 +33,32 @@ class OptableSDKUnitTest {
         assertEquals(eid, OptableSDK.eid(var3))
         assertEquals(eid, OptableSDK.eid(var4))
     }
+
+    @Test
+    fun gaid_isCorrectAndIgnoresCase() {
+        val expected = "g:38400000-8cf0-11bd-b23e-10b96e40000d"
+
+        assertEquals(expected, OptableSDK.gaid("38400000-8cf0-11bd-b23e-10b96e40000d"))
+        assertEquals(expected, OptableSDK.gaid("  38400000-8cf0-11bd-b23e-10b96e40000d"))
+        assertEquals(expected, OptableSDK.gaid("38400000-8cf0-11bd-b23e-10b96e40000d  "))
+        assertEquals(expected, OptableSDK.gaid("  38400000-8cf0-11bd-b23e-10b96e40000d  "))
+        assertEquals(expected, OptableSDK.gaid("38400000-8CF0-11BD-B23E-10B96E40000D"))
+    }
+
+    @Test
+    fun cid_isCorrect() {
+        val expected = "c:FooBarBAZ-01234#98765.!!!"
+
+        assertEquals(expected, OptableSDK.cid("FooBarBAZ-01234#98765.!!!"))
+        assertEquals(expected, OptableSDK.cid(" FooBarBAZ-01234#98765.!!!"))
+        assertEquals(expected, OptableSDK.cid("FooBarBAZ-01234#98765.!!!  "))
+        assertEquals(expected, OptableSDK.cid("  FooBarBAZ-01234#98765.!!!  "))
+    }
+
+    @Test
+    fun cid_isCaseSensitive() {
+        val unexpected = "c:FooBarBAZ-01234#98765.!!!"
+
+        assertNotEquals(unexpected, OptableSDK.cid("foobarBAZ-01234#98765.!!!"))
+    }
 }