このドキュメントは？
- Web版KARTEをご活用済で、KARTE for Appの利用を開始した方に向け、App特有の注意点について記述します。
KARTE for Appでは使用できない機能
KARTE for Appでは、大半の KARTE(web)の機能をご利用頂けますが、一部利用不可の機能がございます。以下、その一部となりますのでご留意下さいませ。（埋め込みのように、CSSセレクタを参照するもの全般は使用不可能となっております。）
- 「埋め込み」テンプレート
- コンテキストイベント（β版）
- Moment Reaction（β版）
- 一部のテンプレート
以下のように、テンプレート選択画面で「i」マークをクリックし、対応デバイスに「iOS/Android」が含まれるものは KARTE for Appでもお使い頂けます
KARTE(web) と、KARTE for App との実装項目の違い
実装形式
- Webでは、計測タグを 対象ウェブサイトHTMLのHEAD部分（全ページ）、カスタムイベントタグを BODY部分（必要な場所のみ）に実装します。また、GTM等のタグマネージャーを利用した導入が可能です。
- Appでは、SDK(Software Development Kit) を、アプリに実装しつつ 閲覧イベント（view）および、カスタムイベントの送信処理や、アプリPUSH通知の連携のための実装等を行います。
SDK（Software Development Kit）とは
- Software Development Kitの略。プログラム部品・開発環境・サンプルコード・技術的な資料等、その技術・部品を使いソフトウェア開発をするための必要項目の一式を指します。
- KARTE for App においては、KARTE(web) の計測タグのようなもののApp版というのが大まかな役割です。
イベントの送信元を識別する _source フィールドの役割
- KARTE for App での KARTEへのイベント送信の際は、
_sourceフィールドを意識する必要があります
_sourceの種類 |
アクセス種類 |
|---|---|
| native_app_sdk | KARTE for App SDKを通じたイベント送信 |
| native_app_webview | KARTEの計測タグを通じたイベント送信（App/WebView連携済） |
| web | KARTEの計測タグを通じたイベント送信（App/WebView連携なし、ブラウザweb） |
| public_api | API v2を通じた通信（バージョン問わず） |
- KARTE for App で扱う
_sourceは、native_app_sdkと、native_app_webviewとなります - これらの
_sourceから送信されたイベントの場合、ユーザーストーリー画面で Appマークが付きます - アプリ内にあるWebViewとネイティブのデータの連係を行う際は、WebViewを計測するをご確認のうえ、実装ください。
app_infoフィールド
- 先の
_sourceでnative_app_sdkもしくはnative_app_webviewのときは、すべてのイベントにapp_infoフィールドが付加され、KARTE SDKのバージョンや、導入のmoduleの種類、該当のアプリのバージョンの情報が入ります。 - 特に、SDKバージョン（karte_sdk_version）やモジュールの種類（module_info）は、良く確認する箇所の一つです。
- app_infoの仕様については、以下サポートサイトをご参考ください。
- app_infoについて
viewイベント（閲覧イベント）の扱い
KARTE(web)と KARTE for Appの閲覧イベントの差
- KARTE(web)との重要な相違点の一つとなります。接客サービスの配信トリガーの設定時にご認識頂く必要がある箇所です。
- KARTE(web)の計測タグとは異なり、KARTE for Appにて画面表示時の閲覧イベント（view）を送るためには、 明示的に viewイベントの送信を実装する必要があります。
- 上記が実装例となります。（iOS/Swiftの場合）
- 一つ目の「signup」は
view_nameフィールドとして送られます。 - 二つ目の「会員登録」は、
titleフィールドとして送られます。 - webであれば、
access.uri.pathなどのフィールドに入るパスの値から、どのページか？を判定しますが ネイティブアプリは、ページを指定するURLが存在しません。 - ネイティブアプリでは これらの
view_nameや、titleを使って判定します。 - 上記はすべて
_sourceが、native_app_sdkのものに限ります。_sourceが、native_app_webviewのイベントは、「計測タグ経由で送信されているが、SDKの機能で App/WebView連携したもの」なので、中身は 計測タグのものと同様、access.uri.path等も利用できます。 native_app_webviewの場合は、view_nameは含まれません。titleは、accessフィールド直下および、エイリアスとして titleフィールドも付与されています。
接客サービスにおける、閲覧イベント（view）を配信トリガーとする際の注意点
- ネイティブの画面と、WebView内のページとで トリガー設定の仕方が異なります
| 画面の種類 | トリガーとするイベント | 指定に使うフィールド |
|---|---|---|
| ネイティブ画面 | 閲覧イベント（view） | view_name もしくは title |
| WebView内ページ | 閲覧イベント（view） | パス(access.uri.path) や URL（access.uri.url）、タイトル（access.uri.title) |
- WebView内ページで接客を指定すると、ブラウザ経由で同じURLのページを閲覧の際にも接客が表示されます。もし、アプリのWebView閲覧時のみ表示の場合は、配信トリガー（対象イベント）の配信チャネルを「アプリのみ」に設定下さい
ネイティブアプリのPUSH通知の仕組み
送信処理の流れ
- （※注「ウェブプッシュ通知」とは異なりますのでご注意ください。）
- KARTEのPUSH通知は、FCM（Firebase Cloud Messaging）を経由して送信します。送信までの流れは、この仕組み のページをご参考ください。
- PUSH通知では、送信対象のデバイスを指定するための「トークン」と、「該当アプリの通知受信許諾情報」の2つを扱います。
- この情報は、
plugin_native_app_identifyというイベントで送信されます - 送信タイミングは、KARTEのアプリPUSH通知の挙動 を参考下さい
- デフォルトのSDKの挙動では、この送信タイミングは制御できず、以下のタイミングで自動的に行われます。
【plugin_native_app_identifyの送信タイミングの主なもの】
アプリの起動時（アプリを完全終了した後の起動）
フォアグラウンドに復帰したタイミング
アプリ完全終了の後の再起動を行うと、トークンやPUSH通知の許諾情報をKARTEに確実に送信することが可能です。お手元の端末での検証の際、アプリPUSH通知が届かない場合は、この操作をまずお試しください。
プッシュ通知におけるセグメント指定時の注意点（休眠ユーザー）
- KARTEでは、該当ユーザーに紐づくイベントが発火した際にセグメント更新が行われます。
- そのため、「最終アクセスから3日経過」などのセグメントは アプリPUSH通知配信では活用頂くことができません。
- 「特定のイベント発生から X日経過後」にPUSH通知を配信する場合は、遅延イベント、またはジャーニー機能 (β) を利用します。（無償版遅延イベントでは、3日後まで可能です。）
【遅延イベントを用いた配信方法】
- 以下の図のように、X日後に自動的に発生する『遅延イベント』を配信トリガーとして指定し、イベント応答配信にて設定します
- 詳細は、KARTE Academy の 「Basic1 + α（for App）」のアプリPUSH通知のパートもご参考ください。
【ジャーニー機能(β)を用いた配信方法】
- 詳細は、 休眠復帰施策のターゲット設定について及び KARTE Academyの「ジャーニーで複数の接客を繋げてシナリオを作ってみよう」をご参照ください。
ネイティブアプリにおける接客表示制御
画面遷移（後述する「画面境界を越える」）の際、接客表示をコントロールする仕組みとなります。
設定には、「無効」「表示を制限する」「常に表示する」の3パターンがございます。
| 設定 | 接客表示が完了後に遷移 | 接客表示が完了する前に遷移 |
|---|---|---|
| 表示を制限する | 表示させない | 表示させない |
| 常に表示する | 表示させる | 表示させる |
| 無効 | 表示させない | 表示させる |
- トリガーイベント発生から、接客の表示まで僅かなタイムラグがあるため、表示前の遷移・表示後の遷移それぞれで制御可能としています。
- 基本的には、ページ遷移が発生したら接客を表示しない「表示を制限する」か、ページ遷移しても表示したままにする「常に表示する」のどちらかを選択ください。
- 「常に表示する」を選ぶ場合はページ遷移で接客が消えないため、モーダルとして必ずユーザーの「閉じる」をする形とするなどの対応が必要になります。
画面境界とは
- KARTEのviewイベントの発生、画面の切り替わりを「画面境界」と呼びます。
- 詳細な定義は以下
- viewイベント以外でも、OSで指定される画面境界が存在するためご注意ください。
KARTE for Appにおけるリンク先制御（ディープリンク）の扱い
- 「アプリの特定の画面に遷移させること」を、ディープリンク（deeplinking）と呼びます。
- ディープリンクには、いくつかの実装手段がございますが、KARTEでは「Custom URL Scheme」を指定する方式が標準となります。
- ディープリンクは、事前実装が必要となります。 事前に遷移が必要な箇所の実装について、アプリ開発者とご確認くださいませ。
ディープリンクの種類
- Custom URL Scheme（URL Scheme）
- KARTE for App のリンク先の指定で使用するものです。
- 例
native-app://category1/1495061/（※ 記述イメージを示すもので、実際には動作致しません。） - 正確には「
native-app」のみを Custom URL Schemeと呼びます。 native-appが、端末内のどのアプリを起動するかを指定します。その後のパラメータcategory1/1495061が、そのアプリのどの場所を開くかの指定をするイメージとなります。- この指定に、アプリでの「実装」が必要 である点にご留意くださいませ。
- この実装が行われない場合、接客をタップしても指定の場所に遷移させることが不可となるためご注意ください。
その他のディープリンクについて
- Universal Links （Apple）や、Android アプリリンク（Google）には KARTE SDKとして標準対応は行っておりませんが、リンク処理の挙動を独自で実装頂くことは可能です。
- 以下のドキュメントを参考ください
【アプリ内メッセージ】
【アプリPUSH通知】
【実装例】
「https://〜」で始まるURLを接客遷移先とした場合の挙動
- アプリ内メッセージ、アプリPUSH通知共に、「https://〜」で始まる ウェブページへのリンクをタップした際は、「標準のブラウザで開く」のがデフォルトの挙動となります。（詳細は前パートのリンク処理に関する iOS/Androidのドキュメントをご参照ください。）
- アプリ内WebViewで指定のURLを開くためには、そのためのCustom URL Shcemeの実装が必要となるため、ご注意ください。
WebViewに関する対応
WebView概要
- ネイティブアプリ内で、Webサイトを表示させる画面の「部品」をWebViewと呼びます
- iOSとAndroidで以下の種類がございます。（どのWebViewで実装されているかは、アプリ開発ご担当者様にご確認くださいませ。）
【iOS】
- WKWebView
- iOSの通常のWebViewです。Webページを表示するだけなので、戻るボタン等は実装されていません。
- Cookie が 標準ブラウザ（Safari）とは、共有されておらず、個別に発行されることにご注意ください。
- そのため、後述する WebView連携実装を行わない場合は、WebView経由ユーザは、アプリユーザーとは認識されず、標準ブラウザ経由アクセスでもない別のユーザーとしてKARTEに認識されます。
- SFSafariViewController
- WKWebViewとは異なり、戻るボタンや閉じるボタンがあります
- Cookie が、標準ブラウザ（Safari）と、共有 されています。
【Android】
- android.webkit.WebView（単にWebViewとも）
- 所謂通常のWebViewです。Webページを表示するだけなので、戻るボタン等は実装されていません
- Cookie が 標準ブラウザ（Google Chrome）と、共有されておらず、個別に発行されることにご注意ください。
- Chrome Custom Tabs
- アプリで、Chromeの画面を呼び出す仕組み
- Cookieが、標準ブラウザ（Chrome）と共有されています
WebView利用のメリット
- アプリの内容更新を行う場合、開発後にアプリストアでの審査・公開対応が必要となるため、更新に掛かる工数が大きいのが一般的です。
- WebViewであれば、Webページ更新によって内容を変えることが可能となります。
WebViewのKARTEの計測について
- WebViewでのウェブサイト閲覧中は、計測は ウェブサイトに設定されたKARTEタグによって行います。
- そのため、KARTE for App の実装過程で、WebView閲覧ページに、WebView専用タグを実装することになります。
- タグがない場合、ネイティブ側（SDK側）では、閲覧中のページのURLのみの取得となるため、Webページ内での行動データの取得のためのタグ実装のご対応をよろしくお願い致します。
App - WebView連携について
- ネイティブ部分と、WebViewで閲覧しているウェブの部分は、それぞれ 別のvisitor idが割り当てられます
- WebView経由でウェブページを閲覧中のユーザーが、ネイティブ部分の利用中のユーザーと同じことを、KARTEタグに伝える処理を「App - WebView連携」と呼びます。
- 具体的な実装は以下からご参照ください。
- WebViewを計測する（iOS/Android）
連携処理には、二通りの実装方法があるため、開発側と確認のうえご対応ください。（ブリッジSDKの種類によっては、現時点でクエリパラメータのみの対応の場合がございます。）
- 【推奨】ユーザースクリプトを利用した方法
- 【非推奨・廃止予定】クエリパラメータを利用した方法
連携が完了すると、WebView経由でページを閲覧した際の
_sourceは、native_app_webviewとなります。（もし未連携の場合はwebとなります。）ユーザーストーリーや、ユーザーリストでも以下のように「App」アイコンが表示されます。
WebView連携周りのトラブルシューティング
以下のサポートサイトをご参考ください。
https://support.karte.io/post/5p11ldZv1FiG7KAGtuO8y1
KARTE for Appのデフォルトイベント
- SDKが標準で送るイベント（iOS）を参照
native_app_installの定義にご注意ください。KARTE SDK導入後の初回起動に該当するイベントのため、インストール数とイコールにはなりません。native_app_openと、native_app_foregroundの違いにご留意ください。plugin_native_app_identifyイベントが発生し、fcm_tokenやsubscribeが送信されていれば、アプリPUSH通知に関するKARTEとの連携実装が完了していることがご確認頂けます。
埋め込みテンプレート、KARTE Blocksの対応状況
- KARTE for App のネイティブ実装部分では、KARTE(web)で利用可能な埋め込みテンプレートが使用不可となります。
- WebView経由で閲覧するウェブページ内では、対応条件を満たしていればご利用可能です。
- なお、KARTE Blocksは、2022年6月時点では WebView内で非対応となりますのでご注意ください。
「設定値配信」について
- 設定値配信は、KARTEからアプリに 値だけを渡す仕組みです。
- アプリ側で、値を受け取って描画実装を行うことで、ネイティブ要素内のバナーの埋め込みに対応することができます
【概念図】
注意点
【設定値配信に必要なモジュールの実装】
- 設定値配信の利用に必要なモジュール（KarteVariables）のインストールが必要になります。
- 参考サポートサイト：
https://developers.karte.io/docs/appendix-module-ios-sdk-v2
https://developers.karte.io/docs/appendix-rich-notification-ios-sdk-v2
【アプリ側にて、実際に描画を行う実装が必須となります】
- 設定値配信では、KARTEはパラメータをアプリに渡すだけのため、パラメータを踏まえての描画は開発実装が必要になります。
- 一般的には、設置場所・表示フォーマット・挙動も含めての実装になります。
- 実装次第で、様々なフォーマットの実現（通常バナー、カルーセル等）が実現可能となります。
- 一つの設定値に、複数のバナーのパラメータを含めることが可能ですが、KARTEでの効果測定（接客数・クリック数など）の単位は、接客サービス・アクション単位となるためご注意ください。
【効果測定用の実装が必要となります】
定値配信でバナー等の表示を行う場合、接客の表示やクリックの実装を別途行う必要がございます。
複数のバナーを1つの設定値配信で制御する場合、KARTE管理画面上では、全バナーの合算値のみが計測される形となるためご留意下さい。分ける場合は、バナー毎に別の接客サービスとして設定下さい。
参考サポートサイト：