Android用SDKでアプリ接客をしたい

はじめに

アプリ接客をするにはSDKの導入が必要です
導入手順の詳細については 以下の記事を参照ください

アプリ接客の導入

Android 版アプリ接客は Android OS 6.0 以降で動作します。

SDK を初期化する

Application クラスを継承した onCreate() で初期化を行います。

public class MyApplication extends Application {

   @Override
    public void onCreate() {
        super.onCreate();

        // アプリ接客を利用するために初期化します
        BDashWebReceptionController.getInstance().init(this);
    }
}

FragmentManagerと導入環境の確認

アプリ接客はサポートライブラリのDialogFragment を利用して実装しています。そのため、画面に表示する際にはActivityとFragmentManagerのインスタンスが必要になります。

アプリ接客を利用するには!!

本機能を利用するに当たり、下記パッケージを組み込む必要があります。
AndroidXの場合:「androidx.fragment.app.FragmentActivity

Actvity のみで構成されているアプリの場合はFragmentActivity.getSupportFragmentManager() で取得した FragmentManager をshowMessage() の第1引数に渡します。

フラグメントを利用しているアプリではgetChildFragmentManager()を引数に設定する必要があります。

ポップアップ表示準備

ポップアップを表示するにはBDashReportクラスに表示条件の情報を設定する必要があります。設定するパラメーターはb→dash画面側と連動します。以下が設定例のサンプルコードを紹介します。

BDashReport report = new BDashReport();

// 設定必須: ターゲットを指定します
report.targets = new String[]{"ターゲット1"}; 

// 設定推奨: トリガーを設定します
report.trigger = BDashReport.TRIGGER_DEFAULT;

// 設定推奨: 現在のスクリーン名を設定します
report.view = "商品画面";

// 設定推奨: 現在のページ名を設定します
report.page = "ProductDetailFragment"; 

// 任意: ひとつ前のスクリーン名を設定します
report.preView = "商品一覧画面";

// 任意: ひとつ前のページ名を設定します
report.prePage = "ProductListFragment"; 

// 任意:発生した関数名を設定します
report.eventFunc= "onCreateView";

// 任意:カスタム値を設定します
report.customProperty= null; 
2021/2現在、trigger,preView,prePage,eventFuncはb→dash管理画面での設定項目がございませんので利用することができません。詳細はカスタマーサクセス担当までお問い合わせください。

ポップアップ表示

ポップアップのインスタンス生成にはBDashWebReceptionController.getIndtance().newPopup()を利用し表示を行うにはBDashWebReception.showMessage()を使います。ポップアップを表示するにはアプリ内コンテンツで表示する場合と、WebViewコンテンツ内で表示させるかで、呼び出すタイミングが異なります。サンプルコードをそれぞれ紹介します。

ーアプリ内コンテンツの実装例のサンプルコードー

public class ProductDetailFragment extends Fragment {
    BDashWebReception bDashWebReception;

public View onCreateView( … ) {
    // インスタンスを管理します
    if( savedInstanceState != null ) {
        // タスクキルされたときに アプリ接客ポップアップを安全に終了させます
        FragmentManager manager = getFragmentManager();
        Fragment fragment =
manager.findFragmentByTag(BDashWebReception.BDASH_FRAGMENT_TAG);
        if( fragment != null ) {
            bDashWebReception = (BDashWebReception) fragment;
            bDashWebReception.dismiss();
      }
}
 // インスタンスを生成します
bDashWebReception = BDashWebReceptionController.getInstance().newPopup();

// ポップアップを表示させます
bDashWebReception.showMessage
    report, // BDashReport を指定します
    getActivity(), // Activity を指定します
    getChildFragmentManager()// FragmentManager を指定します
    );
);
showMessage()においての呼び出しタイミング⁉

上記の showMessage() では、Fragment.onCreateView() のタイミングで実装しておりFragment 作成時にしか呼び出されません。最適な呼び出すタイミングとしては下記となります。

  • インスタンス化は Fragment.onCreateView() で行う
  • ポップアップの表示は Fragment が 「アクティブ」 になったときに行う
    – ライフサイクル関数 onResume で実装するのもほとんどのアプリで有効です。
    – タブ実装のアプリは、タブがアクティブになったタイミングでポップアップを表示するのがベストです。

ーWebView コンテンツの実装例のサンプルコードー

public class ProductDetailFragment extends Fragment {
    BDashWebReception bDashWebReception;
    WebView webView;
public View onCreateView( … ) {
    // インスタンスを管理します
    if( savedInstanceState != null ) {
        // タスクキルされたときに アプリ接客ポップアップを安全に終了させます
        FragmentManager manager = getFragmentManager();
        Fragment fragment =
manager.findFragmentByTag(BDashWebReception.BDASH_FRAGMENT_TAG);
        if( fragment != null ) {
            bDashWebReception = (BDashWebReception) fragment;
            bDashWebReception.dismiss();
        }
    }
    // WebView の読み込み
    webView = view.findViewById(R.id.webView);
    webView.setWebViewClient(webViewClient);
    webView.getSettings().setJavaScriptEnabled(true);
    webView.loadUrl("https://xxxxxxxxxxxxx");

     // インスタンスを生成します
     bDashWebReception = BDashWebReceptionController.getInstance().newPopup();
}

// Webページが表示されるタイミングの検知
WebViewClient webViewClient = new WebViewClient(){
    @Override
    public void onPageFinished(WebView view, String url) {
        super.onPageFinished(view, url);

        BDashReport report = new BDashReport();
        report.targets = new String[]{targetUrl}; 
        report.trigger = BDashReport.TRIGGER_DEFAULT;
        report.view = targetUrl;
        report.preView = lastUrl;
        report.eventFunc = "onPageFinished";

        // ポップアップを表示させます
        bDashWebReception.showMessage(
           report,            // BDashReport を指定します
           getActivity(),    // Activity を指定します
           getChildFragmentManager()// FragmentManager を指定します
        );
    }

    @Override
    public void onPageStarted(WebView view, String url, Bitmap favicon) {
        super.onPageStarted(view, url, favicon);
        // ページ切り替えが発生するときは閉じる
        bDashWebReception.closeMessage();
    }

}

ポップアップ内のアクションイベントを受け取る

ポップアップコンテンツ内にある「ディープリンク」を、エンドユーザーがクリックした際のイベントを受け取ることができます。このとき利用する I/F は BDashWebReception.EventListener のインスタンスを生成し設定します。

  • WebView の場合は、イベント発生時に「url キー」が固定で渡されます
  • Internal の場合は、イベント発生時に「b→dash管理画面で設定したキー」が複数渡されます

実装例のサンプルコードを紹介します。

BDashWebReception bDashWebReception;

// アプリ接客のポップアップイベントリスナー
BDashWebReception.EventListener eventListener = new 
BDashWebReception.EventListener() 
    @Override
    public void onAction(int eventType, HashMap<String, String> parameter) {
        switch(eventType){
           // ディープリンクがインターナルの場合
           case BDashWebReception.EVENT_INTERNAL:

                String action = parameter.get("action");
                break;
      // ディープリングが WebView の場合
           case BDashWebReception.EVENT_WEBVIEW:
                String url = parameter.get("url");
                break;

    }
};
public View onCreateView( … ) {
        // ポップアップイベントのリスナー
        bDashWebReception.setEventListener(eventListener);

        // ポップアップを表示させます
        bDashWebReception.showMessage(
            report,            // BDashReport を指定します
            getActivity(),    // Activity を指定します
            getChildFragmentManager()// FragmentManager を指定します
         );

)

ポップアップを閉じる

アプリ接客の「ポップアップ右上」に設置している「クローズボタン」をエンドユーザーが押下することで閉じられます。またプログラム内で「安全に閉じるため(※)」にAPIを用意しています。実装例のサンプルコードを紹介します。

※画面遷移やライフサイクルイベントなどこの処理を行うにはcloseMessage() を利用します

@Override
public void onPause(){
    super.onPause();

    if( bDashWebReception!=null ) {
        bDashWebReception.closeMessage();
    }
}
closeMesage() は「ポップアップが未表示(準備中)、表示中」に関わらず破棄状態にさせます。画面遷移を行うときは、親となるViewが変わるため必ずcloseMessage()を呼び出す必要があります。

トラッキングレポートを送る

アプリ接客では showMessage() でポップアップを表示する際に「トラッキングレポート」も送付しています。アプリ内シーンで「ポップアップ表示をさせたくない(できない)」タイミングで「トラッキングレポートのみを送る」にはBDashWebReception.report() 関数を利用します。実装例のサンプルコードを紹介します。

BDashReport report = new BDashReport();
report.targets = new String[]{productId}; // 設定必須: ターゲットを指定します
report.trigger = BDashReport.TRIGGER_DEFAULT; // 設定推奨: トリガーを設定します
report.view = "商品画面"; // 設定推奨: 現在のスクリーン名を設定します
report.page = "ProductDetailFragment"; // 設定推奨: 現在のページ名を設定します
report.preView = "商品一覧画面"; // 任意: ひとつ前のスクリーン名を設定します
report.prePage = "ProductListFragment"; // 任意: ひとつ前のページ名を設定します
report.eventFunc= "onCreateView"; // 任意:発生した関数名を設定します
report.customProperty= null; // 任意:カスタム値を設定します

// レポート関数を任意のタイミングで呼び出します
bDashWebReception.report( report );
report() 関数では先に記載したcloseMessage()の影響は一切受けず、成果を送ります。なお通信エラーが発生した場合は、トラッキングと異なり 「リトライ処理」は行われないのでご注意ください。

ポップアップをユーザー毎にカスタマイズする

導入SDKバージョンが2.6.0の場合、実装可能です。

ポップアップを表示する際に、利用ユーザー毎にカスタマイズすること(異なるポップアップを出す等)ができます。実装例のサンプルコードを紹介します。

HashMap<String, String> customProperty = new HashMap<String, String>();
customProperty.put( 
        BDashReport.CUSTOM_LOGIN_USER, // ログインユーザーを示すキーを指定します
        "ログインユーザーID"                // ログインユーザーの値を指定します
);
report.targets = new String[]{"省略"};
report.trigger = BDashReport.TRIGGER_DEFAULT;
report.customProperty = customProperty;

// ポップアップの表示
BDashWebReception popup = BDashWebReceptionController.getInstance().newPopup();
popup.showMessage(report, getActivity(), getChildFragmentManager() );
赤文字の箇所をセットすることで、SDK 側の設定は完了となります。