인앱 메시지

필수 조건

이 기능을 사용하려면 먼저 Roku Braze SDK를 통합해야 합니다. 또한 인앱 메시지는 지원되는 최소 SDK 버전을 실행하는 Roku 기기로만 전송됩니다:

메시지 유형

Roku SDK는 Modal 인앱 메시지만 지원합니다.

표시 방법 선택하기

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는 다음 필드를 사용하며, 그 외 필드는 무시합니다.

표시 및 닫기

각 Modal 메시지에 대해 SDK는 다음 작업을 수행합니다.

1. display_delay가 설정된 경우 해당 시간(초)만큼 기다립니다.
2. 전체화면 BrazeDefaultInAppMessage 오버레이를 Scene에 추가하고 포커스를 부여합니다.
3. 노출 횟수를 기록합니다.
4. BrazeTask.BrazeInAppMessage를 지웁니다.
5. 메시지가 닫히면 오버레이를 제거하고 포커스를 복원합니다.

dismiss_type이 AUTO_DISMISS인 경우 메시지는 duration밀리초 후에 닫히며 클릭은 기록되지 않습니다. 그 외의 경우에는 사용자가 닫을 때까지 메시지가 유지됩니다.

SDK는 한 번에 하나의 메시지만 표시하며 메시지를 대기줄에 넣지 않습니다.

• 새 메시지가 도착하면 아직 display_delay를 기다리고 있는 메시지가 취소됩니다.
• 새 메시지는 자체 display_delay가 지나 표시될 때 화면에 있는 메시지를 대체합니다.
• 삭제된 메시지(MODAL이 아니거나 message 값이 없는 메시지)는 다른 메시지를 취소하거나 대체하지 않습니다.

리모컨

포커스

오버레이가 표시되어 있는 동안 콘텐츠 로드, 화면 전환, 비디오 재생 등으로 앱이 setFocus를 호출하면 오버레이가 포커스를 다시 가져옵니다. 메시지가 닫히면 앱에서 마지막으로 포커스를 준 노드로 포커스가 돌아갑니다.

오버레이가 표시되어 있는 동안 앱에서 Scene 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 대시보드에서 메시지 또는 버튼의 클릭 시 동작을 앱이 인식할 수 있는 URI(예: myapp://details/123)를 사용하는 딥링크로 설정합니다. 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단계: 트리거된 메시지에 액세스하기

그런 다음 핸들러 내에서 Campaigns가 트리거한 가장 우선순위가 높은 인앱 메시지에 액세스할 수 있습니다.

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는 기본적으로 꺼져 있으므로 업그레이드해도 인앱 메시지가 표시되는 방식은 바뀌지 않습니다. 다음 중 한 가지 방법을 선택하세요.

커스텀 UI 유지하기

1. 기존 SDK 파일을 2.3.0 릴리스의 sdk_files 디렉토리에 있는 파일로 교체합니다.
2. automatic_iam_display는 설정하지 않은 상태로 둡니다.

옵저버, UI, 로깅은 모든 메시지 유형에서 이전과 동일하게 작동합니다. SDK는 automatic_iam_display가 true인 경우에만 BrazeDefaultInAppMessage 파일을 사용하므로, 나머지 sdk_files와 함께 복사해도 안전합니다.

기본 UI로 전환하기

1. 기존 SDK 파일을 2.3.0 릴리스의 sdk_files 디렉토리에 있는 파일로 교체하고, BrazeDefaultInAppMessage.brs, BrazeDefaultInAppMessage.xml, BrazeDefaultInAppMessageStyles.brs 파일을 components에 추가합니다. 기존 샘플 BrazeInAppMessage 컴포넌트는 변경되지 않습니다. 전환한 후에는 삭제해도 됩니다.
2. 기본 UI를 켭니다.
3. Scene에서 getBrazeInstance()가 호출되는지 확인합니다.
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 애플리케이션 내에서 인앱 메시지를 구현하고 스타일을 지정할 수도 있습니다.

버튼