add getUserSyncScript api (#189)

* add getUserSyncScript api
deprecated appendUserSyncQueryParameter api.

CHANGELOG.md

@@ -2,13 +2,21 @@
 
 | モジュール/プラグイン名 | Description | 最新のバージョン |
 | :-- | :-- | :-- |
-| core | イベントトラッキング機能を提供します。 | 2.18.0 |
+| core | イベントトラッキング機能を提供します。 | 2.19.0 |
 | inappmessaging | アプリ内メッセージ機能を提供します。 | 2.13.0 |
 | notifications | プッシュ通知の受信および効果測定機能を提供します。 | 2.8.0 |
 | variables | 設定値配信機能を提供します。 | 2.2.0 |
 | visualtracking | ビジュアルトラッキング機能を提供します。| 2.6.0 |
 | Karte Gradle Plugin | ビジュアルトラッキング機能に必要なプラグインです。| 2.4.0 |
 
+# Releases - xxxx.xx.xx
+
+### Core 2.19.0
+** 🎉FEATURE**
+- WebView連携のための補助APIとして `UserSync.getUserSyncScript` を追加しました。
+  - 返されるスクリプトをWebViewで実行することで、`android.webkit.WebView`以外のWebViewに対してもユーザー連携が可能になります。
+  - これに伴い、クエリパラメータ連携API `UserSync.appendUserSyncQueryParameter` は非推奨になります。
+
 # Releases - 2022.06.02
 
 ### Core 2.18.0

core/src/main/java/io/karte/android/core/usersync/UserSync.kt

@@ -36,7 +36,7 @@ private const val PARAM_TIMESTAMP = "ts"
 /**
  * WebView 連携するためのクラスです。
  *
- * WebページURLに連携用のクエリパラメータを付与した状態で、URLをWebViewで開くことでWebとAppのユーザーの紐付けが行われます。
+ * Webページを開くWebViewに連携用のスクリプトを設定することで、WebとAppのユーザーの紐付けが行われます。
  *
  * なお連携を行うためにはWebページに、KARTEのタグが埋め込まれている必要があります。
  */
@@ -49,7 +49,9 @@ object UserSync {
      * 指定されたURL文字列の形式が正しくない場合、またはSDKの初期化が行われていない場合は、引数に指定したURL文字列を返します。
      */
     @JvmStatic
+    @Deprecated("User sync function using query parameters is deprecated. It will be removed in the future.", ReplaceWith("setUserSyncScript(webView)"))
     fun appendUserSyncQueryParameter(url: String): String {
+        @Suppress("DEPRECATION")
         return appendUserSyncQueryParameter(Uri.parse(url))
     }
 
@@ -61,6 +63,7 @@ object UserSync {
      * SDKの初期化が行われていない場合は、引数に指定したUriを文字列で返します。
      */
     @JvmStatic
+    @Deprecated("User sync function using query parameters is deprecated. It will be removed in the future.", ReplaceWith("setUserSyncScript(webView)"))
     fun appendUserSyncQueryParameter(uri: Uri): String {
         val param = buildUserSyncParameter() ?: return uri.toString()
 
@@ -73,6 +76,20 @@ object UserSync {
             .toString()
     }
 
+    /**
+     * WebView 連携用のスクリプト(javascript)を返却します。
+     *
+     * ユーザースクリプトとしてWebViewに設定することで、WebView内のタグと連携されます。
+     *
+     * なおSDKの初期化が行われていない場合はnullを返却します。
+     * @param[webView] [WebView]
+     */
+    @JvmStatic
+    fun getUserSyncScript(): String? {
+        val syncParam = buildUserSyncParameter() ?: return null
+        return String.format("window.__karte_ntvsync = %s;", syncParam)
+    }
+
     /**
      * WebViewに連携用のスクリプトを設定します。
      *
@@ -86,11 +103,8 @@ object UserSync {
         webView: WebView
     ) {
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
-            val script = String.format(
-                "window.__karte_ntvsync = %s;",
-                buildUserSyncParameter()
-            )
-            webView.evaluateJavascript(script) { }
+            val syncScript = getUserSyncScript() ?: return
+            webView.evaluateJavascript(syncScript) { }
         }
     }
 

core/src/test/java/io/karte/android/integration/DryRunTest.kt

@@ -73,7 +73,9 @@ class DryRunTest : DryRunTestCase() {
 
     @Test
     fun testUserSync() {
+        @Suppress("DEPRECATION")
         assertThat(UserSync.appendUserSyncQueryParameter("test")).isEqualTo("test")
+        assertThat(UserSync.getUserSyncScript()).isNull()
 
         UserSync.setUserSyncScript(WebView(application))
         assertDryRun()

core/src/test/java/io/karte/android/integration/OptOutTest.kt

@@ -117,10 +117,18 @@ class OptOutTest {
                             Base64.NO_WRAP
                         ), "utf8"
                     )
+                    @Suppress("DEPRECATION")
                     val syncParam =
                         UserSync.appendUserSyncQueryParameter("https://plaid.co.jp")
                     assertThat(syncParam).contains(expected)
                 }
+
+                @Test
+                fun UserSyncScriptに_karte_tracker_deactivateが追加されること() {
+                    val param = "{\"_karte_tracker_deactivate\":true}"
+                    val syncScript = UserSync.getUserSyncScript()
+                    assertThat(syncScript).contains(param)
+                }
             }
 
             class OptIn実行 : OptOutTestCase() {
@@ -163,10 +171,18 @@ class OptOutTest {
                             Base64.NO_WRAP
                         ), "utf8"
                     )
+                    @Suppress("DEPRECATION")
                     val syncParam =
                         UserSync.appendUserSyncQueryParameter("https://plaid.co.jp")
                     assertThat(syncParam).doesNotContain(expected)
                 }
+
+                @Test
+                fun UserSyncScriptに_karte_tracker_deactivateが追加されないこと() {
+                    val param = "{\"_karte_tracker_deactivate\":true}"
+                    val syncScript = UserSync.getUserSyncScript()
+                    assertThat(syncScript).doesNotContain(param)
+                }
             }
         }
     }

core/src/test/java/io/karte/android/unit/UserSyncTest.kt

@@ -64,6 +64,7 @@ class UserSyncTest : RobolectricTestCase() {
 
     @Test
     fun appendUserSyncQueryParameter_String() {
+        @Suppress("DEPRECATION")
         val actual = UserSync.appendUserSyncQueryParameter("https://plaid.co.jp?hoge=fuga")
         val base64EncodedString = Uri.parse(actual).getQueryParameter("_k_ntvsync_b")
         val string = String(Base64.decode(base64EncodedString, Base64.NO_WRAP))
@@ -73,6 +74,7 @@ class UserSyncTest : RobolectricTestCase() {
 
     @Test
     fun appendUserSyncQueryParameter_Uri() {
+        @Suppress("DEPRECATION")
         val actual =
             UserSync.appendUserSyncQueryParameter(Uri.parse("https://plaid.co.jp?hoge=fuga"))
         val base64EncodedString = Uri.parse(actual).getQueryParameter("_k_ntvsync_b")
@@ -89,4 +91,12 @@ class UserSyncTest : RobolectricTestCase() {
         val actual = customShadowOf(webView).lastEvaluatedJavascript
         Assert.assertEquals(expected, actual)
     }
+
+    @Test
+    fun getUserSyncScript() {
+        val expected = String.format("window.__karte_ntvsync = %s;", expected)
+
+        val actual = UserSync.getUserSyncScript()
+        Assert.assertEquals(expected, actual)
+    }
 }

core/version

@@ -1 +1 @@
-2.18.0
+2.19.0