アプリ内メッセージ

アプリ内メッセージとは

アプリ内メッセージとは、アプリ起動中のユーザーに向けてポップアップなどのメッセージを表示させることができる機能です。

この機能を使用することで、下記のようなことが実現できます。

お知らせを OFF にしているユーザーに対してアプローチを行う
- （お知らせを ON にするように設定画面への遷移を促す、など）
アプリのトップ画面を開いた際、キャンペーンなどのバナーを表示させる
商品をカートに入れたユーザーに対しクーポンを付与するようなバナーを表示させる

アプリ内メッセージは、契機となるイベントトラッキングの付与が正しく組み込まれていれば、本SDKを組み込むだけで受信できるようになります。

後方互換性のない仕様変更

SDK バージョン 6.2.0 において、アプリ内メッセージにおける後方互換性のない仕様変更が行われております。

詳細についてはこちらをご参照ください。

なお、バージョン 6.2.0 未満のSDKをご利用の場合は、旧SDK組み込みガイドをご確認ください。

イベントトラッキングを付与する

アプリ内メッセージを表示させるためには、必ずイベントトラッキングを付与する必要があります。

イベントトラッキングの付与には下記のメソッドを呼び出してください。

PopinfoReceiver.shared.trackEvent("イベントキー名", value: [
    "testName1": "testVal1",
    "testName2": "testVal2"
])

第1引数にはイベントのキー名を、第2引数にはイベントのキーに対する値を辞書型で格納します。

イベント付与タイミングにご注意ください

許諾ダイアログのような iOS 由来のダイアログと、アプリ内メッセージが両方表示されてしまわないよう、イベントを付与するタイミングにはご注意ください。
例えば、loadSettings をコールするタイミングで上記のようなイベントをつけた場合、iOS のダイアログと同時にアプリ内メッセージが表示されてしまいます。

デリゲートメソッドについて

公開されている各種デリゲートを利用し、アプリ内メッセージの一部の処理に割り込むことが出来ます。

デリゲートメソッドを利用するためには、まず以下のように実装を行います。

PopinfoReceiver と同様に PopinfoEventActionReceiver のクラスのインスタンスとプロトコルの宣言を行います。
App 起動時にコールされる application:didFinishLaunchingWithOptions: 内で同クラスのインスタンスを生成します。

class AppDelegate: UIApplicationDelegate, UNUserNotificationCenterDelegate, PopinfoReceiverDelegate, PopinfoEventActionReceiverDelegate {
    var popinfoReceiver: PopinfoReceiver!
    var popinfoEventActionReceiver: PopinfoEventActionReceiver!
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        self.popinfoReceiver = PopinfoReceiver.shared
        self.popinfoReceiver.delegate = self
        self.popinfoEventActionReceiver = PopinfoEventActionReceiver.shared
        self.popinfoEventActionReceiver.delegate = self
        // ...省略...
    }
    // ...省略...
}

以下、デリゲートメソッドの一部をご紹介します。

利用可能なすべてのデリゲートについては付属のAPIドキュメントを参照してください

組み込み側でメッセージの表示可否を判定する

アプリ内メッセージのトリガーとなったイベント名やカテゴリ等をもとに、該当のアプリ内メッセージを表示するかどうかを決定することができます。

func popinfoEventActionReceiver(_ popinfoEventActionReceiver: PopinfoEventActionReceiver, shouldDisplay inAppMessage: PopinfoInAppMessage, event: String, category: String) -> Bool {
    // ここで false を返すと、アプリ内メッセージは表示されません
    // 表示しようとしているアプリ内メッセージの情報(HTML等)は、変数 inAppMessage に格納されます
    return true
}

実装しなかった場合は true が返却されたものとして扱われます。

アプリ内メッセージのボタンがタップされた際にURLを取得する

func popinfoEventActionReceiver(_ popinfoEventActionReceiver: PopinfoEventActionReceiver, receivedTapActionAndGetUrl urlString: String) {
    // 例: 取得したURLをブラウザで開く
    UIApplication.shared.open(URL(string: url)!, options: [:], completionHandler: nil)
}

アプリ内メッセージ内部に配置されたボタンには遷移先URLを指定できますが、エンドユーザーがボタンをタップした際に、そのURLを取得することができます。

例えば、エンドユーザーがボタンをタップした場合に該当URLにアクセスするような実装を行う場合に使用します。

アプリ内メッセージの表示について

任意のタイミングでアプリ内メッセージを表示

バージョン 6.2.0 から、アプリ内メッセージを任意のタイミングで表示することができるようになりました。

同SDKバージョンから、「組み込み側でメッセージの表示可否を判定する」ためのデリゲートにおいて、アプリ内メッセージのオブジェクトを取得できるようになりましたので、これを任意の場所（UserDefaultsなど）に保存し、任意のタイミングで表示させることができます。

下記を参考に実装してください。

func popinfoEventActionReceiver(_ popinfoEventActionReceiver: PopinfoEventActionReceiver, shouldDisplay inAppMessage: PopinfoInAppMessage, event: String, category: String) -> Bool {
    // 表示しようとしているアプリ内メッセージの情報を保存します
    save(inAppMessage)

    // アプリ内メッセージは後で表示したいので、ここでは false を返し、表示処理を中断します
    return false
}

// アプリ内メッセージを表示したいタイミングになったら、このメソッドが呼ばれるようにします
func displayInAppMessage() {
    // 保存したアプリ内メッセージを読み込みます
    let inAppMessage: PopinfoInAppMessage = loadMessage()

    // アプリ内メッセージを表示します
    PopinfoInAppMessageViewController().display(message: inAppMessage)
}

アプリ内メッセージViewControllerのカスタマイズ

SDKバージョン6.2.0から、アプリ内メッセージのViewController関連クラスが利用できるようになりました。

これにより、アプリ内メッセージの表示を組み込み側からカスタマイズできるようになります。

Memo

このセクションでは、便宜上「デフォルトIVC」と「カスタムIVC」という単語を使用します。

定義は以下の通りです:

デフォルトIVC: SDKが参照するアプリ内メッセージのためのViewControllerで、初期状態ではPopinfoInAppMessageBaseViewController クラスを指す。
カスタムIVC: デフォルトIVCを継承して作成した、組み込み側でカスタマイズ可能なViewController

カスタムIVCの作成について

アプリ内メッセージの表示（レイアウトなど）をカスタマイズしたい場合は、デフォルトIVCを継承してカスタムIVCを作成することをおすすめします。

デフォルトIVCを継承せずに独自のViewControllerを作成することも可能ですが、その場合下記の機能がご利用いただけませんので、ご注意ください。

アプリ内メッセージ固有のイベントトラッキング
アプリ内メッセージ表示回数制限に基づく表示制御
アプリ内メッセージ表示期間制限に基づく表示制御
ボタンタップ時のデリゲート通知

カスタムIVCをデフォルトIVCとして登録する

アプリ内メッセージの表示処理を独自で行わずにSDKに委ねる場合、SDKは PopinfoInAppMessageBaseViewController を用いてアプリ内メッセージを表示します。

そのため、独自のカスタムIVCを使用してアプリ内メッセージを表示させたい場合は、SDKにカスタムIVCを連携する必要があります。

カスタムIVCを連携するには、PopinfoEventActionReceiver のプロパティ defaultViewController に、カスタムIVCのインスタンスを登録します。（下記をご参照ください。）

self.popinfoEventActionReceiver = PopinfoEventActionReceiver.shared
self.popinfoEventActionReceiver.delegate = self

// CustomInAppMessageViewController を、SDKがアプリ内メッセージ表示時に使用するViewControllerとして登録します
self.popinfoEventActionReceiver.defaultViewController = CustomInAppMessageViewController()

デバッグモードについて

PopinfoConfiguration.m において popinfoTestLogUse を YES に設定すると、アプリ内メッセージを表示するためのイベントが発生したタイミングで、コンソールにイベントのキー名を表示することが出来ます。

コンソール表示の書式

<キー名> matched. (現在の1日の表示回数,1日の最大表示回数)(トータル表示回数、トータル最大表示回数)

コンソール表示の例

<app.top> matched. (1,5)(1,-)

APIの設定値を変更する

アプリ内メッセージにおいては、以下の設定値を変更することができます。

付属のファイル SdkSettings.plist において、該当箇所を下記条件に従って変更してください。

キー	説明	初期値	最小値	最大値
EventActionApiCallMaxWaitSec	アプリ内メッセージ用のAPIコールにおけるタイムアウト値（単位：秒）	10	5	60
EventActionApiRetryCountLimit	アプリ内メッセージ用APIのコールが失敗した際に、再試行を行う回数の最大値	5	0	10

変更後の値がそれぞれの最小値以下または最大値以上だった場合は初期値が適用されます。

その他の注意事項

CoreData モデルバージョンは必ず最新バージョンに設定してください

最新になっていない場合、アプリ内メッセージを正常に受け取れないだけでなく、App実行時にクラッシュを引き起こす原因にもなります。
CoreData モデルのバージョン確認方法はこちらを参考にしてください。

通信に関する注意

アプリ内メッセージは表示の際にサーバーとの通信が発生します。
そのため、通信状況などによって表示が遅れたり、まれに表示自体が失敗することがあります。

アプリ内メッセージをトリガーにしないでください

「アプリ内メッセージが表示されていないとログインが行われない」といったように、後続処理のトリガーとしてアプリ内メッセージを利用した場合、通信状況によってはアプリに対するユーザーエクスペリエンスを著しく低下させてしまう場合があります。