アプリ内メッセージ

前提条件

この機能を使用するには、Roku Braze SDKを統合する必要があります。 また、アプリ内メッセージは、最低限サポートされているSDKバージョンを実行しているRokuデバイスにのみ送信されます。

メッセージタイプ

Roku SDKは、モーダルアプリ内メッセージのみをサポートしています。

表示方法の選択

Roku SDK 2.3.0以降では、SDKがアプリ内メッセージを表示できます。独自のUIでレンダリングを続けることもできます。

アップグレード中で、すでにカスタムUIを使用している場合は、Roku SDK 2.3.0へのアップグレードを参照してください。デフォルトUIをオンにしない限り、カスタムUIは引き続き動作します。

デフォルトUIの使用

重要

デフォルトUIには、Roku SDK 2.3.0以降が必要です。

ステップ1: デフォルトUIファイルを追加する

Braze Roku SDKリポジトリのsdk_files/componentsディレクトリから、以下のファイルをアプリのcomponentsディレクトリに追加します。

• BrazeDefaultInAppMessage.brs
• BrazeDefaultInAppMessage.xml
• BrazeDefaultInAppMessageStyles.brs

これらのファイルがない場合、SDKはBrazeDefaultInAppMessage component not foundをログに記録し、メッセージを表示しません。

ステップ2: デフォルトUIをオンにする

main.brsで、Braze設定のautomatic_iam_displayをtrueに設定します。

1
2

config[config_fields.AUTOMATIC_IAM_DISPLAY] = true
globalNode.addFields({brazeConfig: config})

ステップ3: SceneからBrazeを初期化する

SceneコンポーネントからgetBrazeInstance()を呼び出します。たとえばinit()内で呼び出します。

1
2
3
4

sub init()
    m.BrazeTask = CreateObject("roSGNode", "BrazeTask")
    m.Braze = getBrazeInstance(m.BrazeTask)
end sub

警告

他のコンポーネントからgetBrazeInstance()を呼び出すと、SDKはオーバーレイをSceneにアタッチできず、メッセージは失われます。

デフォルトのメッセージについては、BrazeTask.BrazeInAppMessageを監視したり、UIを作成したりする必要はありません。

デフォルトUIの仕組み

サポートされるメッセージ

デフォルトUIは MODAL のアプリ内メッセージのみを表示します。その他のタイプはSDKによって破棄され、エラーがログに記録されます。

デフォルトUIは次のフィールドを使用し、それ以外のフィールドは無視します。

表示と閉じる動作

モーダルメッセージごとに、SDKは次の処理を行います。

1. display_delay が設定されている場合は、その秒数だけ待機します。
2. 全画面の BrazeDefaultInAppMessage オーバーレイをシーンに追加し、フォーカスを与えます。
3. インプレッションをログに記録します。
4. BrazeTask.BrazeInAppMessage をクリアします。
5. メッセージが閉じられると、オーバーレイを削除してフォーカスを元に戻します。

dismiss_type が AUTO_DISMISS の場合、メッセージは duration ミリ秒後に閉じられ、クリックはログに記録されません。それ以外の場合、メッセージはユーザーが閉じるまで表示されたままになります。

SDKは一度に1つのメッセージのみを表示し、メッセージをキューに入れることはありません。

• 新しいメッセージは、display_delay の待機中のメッセージをキャンセルします。
• 新しいメッセージは、自身の display_delay の経過後に表示される時点で、画面上のメッセージを置き換えます。
• 破棄されたメッセージ (MODAL ではないもの、または message の値がないもの) は、何もキャンセルしたり置き換えたりしません。

リモコン操作

フォーカス

オーバーレイの表示中に、コンテンツの読み込み、画面の切り替え、動画の再生などでアプリが setFocus を呼び出した場合、オーバーレイがフォーカスを取り戻します。メッセージが閉じられると、アプリが最後にフォーカスしたノードにフォーカスが戻ります。

オーバーレイの表示中にアプリがシーンの dialog を開いた場合、そのダイアログは閉じられるまでフォーカスを保持します。

クリックとディープリンクの処理

SDKはURIを開きません。メッセージのclick_actionとuriを処理するには、SceneにbrazeHandleInAppMessageClick(event)を実装し、Sceneの<interface>で宣言します。宣言されていない場合、SDKはこの関数を呼び出しません。

1
2
3
4
5
6

<component name="MainScene" extends="Scene">
    <interface>
        <function name="brazeHandleInAppMessageClick" />
    </interface>
    ...
</component>

eventパラメーターの構造は次のとおりです。

1
2
3
4
5

{
    in_app_message: <message AA>,
    button:         <button AA, or invalid for a body click>,
    button_index:   <0 or 1, or -1 for a body click>
}

次の点に注意してください。

• SDKはオーバーレイを削除してフォーカスを復元した後にこの関数を呼び出すため、この関数から新しい画面を開くことができます。
• click_actionが"NONE"のボタンもこの関数を呼び出します。アクションを実行する前にclick_actionを確認してください。
• SDKは戻り値を無視します。
• ユーザーが×の閉じるボタン、戻る、またはAUTO_DISMISSでメッセージを閉じた場合、SDKはこの関数を呼び出しません。
• brazeHandleCustomInAppMessageでレンダリングするメッセージに対しては、SDKはこの関数を呼び出しません。

例：ディープリンクのルーティング

1. Brazeダッシュボードで、メッセージまたはボタンのクリック時の動作を、myapp://details/123のようなアプリが解釈できるURIを持つディープリンクに設定します。SDKはこれをclick_action = "URI"として配信し、URIはuriに格納されます。
2. brazeHandleInAppMessageClickでURIを解析し、対応する画面にルーティングします。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

function brazeHandleInAppMessageClick(event as object) as boolean
    target = event.button
    if target = invalid then target = event.in_app_message

    if target.click_action <> "URI" then return false
    if target.uri = invalid then return false

    uri = target.uri.ToStr()
    prefix = "myapp://details/"
    if Left(uri, Len(prefix)) = prefix
        ' ShowDetailsScreen is a function in your app.
        ShowDetailsScreen(Mid(uri, Len(prefix) + 1))
        return true
    end if
    return false
end function

注

uriの値は、ダッシュボードの値が数値である場合など、数値として届くことがあります。解析する前にToStr()で変換してください。

カスタムUIで特定のメッセージをレンダリングする

一部のメッセージを独自のUIでレンダリングし、残りのメッセージにはデフォルトUIを使用するには、SceneにbrazeHandleCustomInAppMessage(in_app_message)を実装し、Sceneの<interface>で宣言します。

SDKは、display_delayの経過後、MODALメッセージごとにこの関数を呼び出します。メッセージをレンダリングした場合はtrueを返します。デフォルトUIで表示する場合はfalseを返します。

1
2
3
4

<interface>
    <function name="brazeHandleCustomInAppMessage" />
    <function name="brazeHandleInAppMessageClick" />
</interface>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

function brazeHandleCustomInAppMessage(in_app_message as object) as boolean
    if in_app_message.extras <> invalid and in_app_message.extras.msgtype = "sidebyside"
        ' getDeepestFocusedNode is a helper in the sample app's MainScene.brs.
        m.oldFocus = getDeepestFocusedNode(m.top.focusedChild)
        m.customMsg = CreateObject("roSGNode", "CustomSideBySideInAppMessage")
        m.top.appendChild(m.customMsg)
        m.customMsg.BrazeTask = m.BrazeTask
        m.customMsg.inappmessage = in_app_message
        m.customMsg.setFocus(true)
        m.customMsg.ObserveField("isClosed", "reclaimFocus")
        return true
    end if
    return false
end function

sub reclaimFocus()
    m.top.removeChild(m.customMsg)
    m.customMsg = invalid
    if m.oldFocus <> invalid then m.oldFocus.setFocus(true)
end sub

完全なカスタムコンポーネントについては、Braze Roku SDKリポジトリにあるtorchietvサンプルアプリのCustomSideBySideInAppMessageを参照してください。

以下の点に注意してください。

• SDKがこの関数を呼び出すのは、automatic_iam_displayがtrueで、デフォルトUIファイルがアプリに含まれている場合のみです。
• この関数に渡されるのはMODALメッセージのみです。
• カスタムUIは、インプレッション、クリック、ボタンクリックのログ記録、自身のノードの削除、フォーカスの復元を担当します。
• SDKはBrazeTask.BrazeInAppMessageのクリアとdisplay_delayの適用を自動で行うため、これらを自分で処理しないでください。
• 新しいメッセージが届くと、SDKはこの関数を呼び出す前にデフォルトのオーバーレイを削除します。ただし、以前にレンダリングしたカスタムレイアウトは削除できないため、Scene側で削除してください。

すべてのメッセージにカスタムUIを使用する

automatic_iam_display を未設定のままにすると、アプリがすべてのアプリ内メッセージを処理します。オブザーバー、UI、およびログ記録は、すべてのメッセージタイプについてRoku SDK 2.3.0より前と同様に動作します。

ステップ1: オブザーバーを追加する

アプリ内メッセージを処理するには、BrazeTask.BrazeInAppMessage にオブザーバーを追加します。

1

m.BrazeTask.observeField("BrazeInAppMessage", "onInAppMessageReceived")

ステップ2: トリガーされたメッセージにアクセスする

次に、ハンドラー内で、キャンペーンによってトリガーされた最も優先度の高いアプリ内メッセージにアクセスできます。

1
2
3
4

sub onInAppMessageReceived()
  in_app_message = m.BrazeTask.BrazeInAppMessage
  ...
end sub

Roku SDK 2.3.0へのアップグレード

Roku SDK 2.3.0では、デフォルトUIが追加されています。デフォルトではオフになっているため、アップグレードしてもアプリ内メッセージの表示方法は変わりません。以下のいずれかの方法を選択してください。

カスタムUIを維持する

1. 既存のSDKファイルを、2.3.0リリースのsdk_filesディレクトリにあるファイルに置き換えます。
2. automatic_iam_displayは未設定のままにします。

オブザーバー、UI、ログ記録は、すべてのメッセージタイプでこれまでどおり動作します。SDKがBrazeDefaultInAppMessageファイルを使用するのはautomatic_iam_displayがtrueの場合のみであるため、sdk_filesのほかのファイルと一緒にコピーしても問題ありません。

デフォルトUIに切り替える

1. 既存のSDKファイルを2.3.0リリースのsdk_filesディレクトリにあるファイルに置き換え、BrazeDefaultInAppMessage.brs、BrazeDefaultInAppMessage.xml、BrazeDefaultInAppMessageStyles.brsの各ファイルをcomponentsに追加します。以前のサンプルBrazeInAppMessageコンポーネントは変更されません。切り替えた後は削除してかまいません。
2. デフォルトUIをオンにします。
3. getBrazeInstance()がSceneから呼び出されていることを確認します。
4. 既存のアプリ内メッセージ処理を削除します。
   • オブザーバー：m.BrazeTask.observeField("BrazeInAppMessage", "onInAppMessageReceived")とそのハンドラー
   • アプリ内メッセージノードの作成と追加
   • LogInAppMessageImpression、LogInAppMessageClick、LogInAppMessageButtonClickの呼び出し
   • m.BrazeTask.BrazeInAppMessage = invalid
5. クリックとディープリンクの処理をbrazeHandleInAppMessageClickに移動します。

警告

SDKは独自のオブザーバーを追加し、既存のオブザーバーを置き換えることはありません。デフォルトUIをオンにしたときにオブザーバーとログ記録を残したままにすると、メッセージが二重に表示され、インプレッションとクリックも二重に記録される可能性があります。

一部のカスタムレイアウトを維持する

デフォルトUIに切り替えるの手順に従います。その後、以前のハンドラーにあるレンダリングコードをbrazeHandleCustomInAppMessageに移動します。

以前のハンドラーとの違いは次のとおりです。

• インプレッションとクリックのログ記録は残します。
• 独自のノードの削除とフォーカスの復元は引き続き行います。
• m.BrazeTask.BrazeInAppMessage = invalidは削除します。SDKがクリアします。
• 独自のdisplay_delay処理は削除します。SDKが適用します。
• この関数に渡されるのはMODALメッセージのみです。ほかのメッセージタイプをレンダリングする場合は、すべてのメッセージで引き続きカスタムUIを使用してください。

メッセージフィールド

これらのフィールドは、カスタムUIでメッセージをレンダリングする際に in_app_message で使用できます。デフォルトUIでは、これらが自動的に適用されます。

処理

アプリ内メッセージを処理するために必要なフィールドは次のとおりです。

重要

ボタンを含むアプリ内メッセージでは、ボタンテキストを追加する前にクリックアクションを追加した場合、メッセージの click_action も最終的なペイロードに含まれます。

スタイル設定

ダッシュボードから使用できるさまざまなスタイル設定フィールドもあります。

または、標準パレットを使用して、Rokuアプリケーション内でアプリ内メッセージを実装し、スタイルを設定することもできます。

ボタン