인앱 메시지 트리거

Braze SDK를 통해 인앱 메시지를 트리거하는 방법을 알아보세요.

메시지 트리거 및 전달

인앱 메시지는 SDK가 다음 커스텀 이벤트 유형 중 하나를 기록할 때 트리거됩니다: Session Start, Push Click, Any Purchase, Specific Purchase, Custom Event(마지막 두 가지는 강력한 속성정보 필터를 포함합니다).

사용자 세션이 시작되면 Braze는 적격한 모든 인앱 메시지를 사용자의 기기로 전달하며, 동시에 에셋을 미리 가져와 표시 지연 시간을 최소화합니다. 트리거 이벤트에 적격한 인앱 메시지가 두 개 이상인 경우, 우선순위가 가장 높은 메시지만 전달됩니다. 자세한 내용은 세션 생명주기를 참조하세요.

참고

인앱 메시지는 API 또는 API 이벤트를 통해 트리거할 수 없으며—SDK가 기록한 커스텀 이벤트로만 트리거할 수 있습니다. 기록에 대해 자세히 알아보려면 커스텀 이벤트 기록을 참조하세요.

인앱 메시지 유형

Braze는 세션 시작 시 사용자 기기에 inapp과 templated_iam이라는 두 가지 유형의 인앱 메시지를 전송합니다. 대시보드 사용자에게는 이러한 유형의 차이가 보이지 않지만, Braze는 설정과 콘텐츠에 따라 각 유형을 다르게 처리합니다.

inapp (표준)

inapp(또는 “표준”) 인앱 메시지는 Braze가 이미 알고 있는 커스텀 속성 등 필요한 정보가 이미 템플릿화되어 있습니다. 일반적으로 인앱 메시지가 기기에 다운로드되면, 트리거 이벤트가 발생할 때 기기가 오프라인이거나 비행기 모드인 경우에도 SDK가 inapp 인앱 메시지를 표시합니다.

templated_iam (템플릿)

templated_iam(또는 “템플릿”) 인앱 메시지는 아직 필요한 정보가 템플릿화되지 않은 상태입니다. 메시지가 표시되기 전에 Braze가 추가 요청을 통해 정보를 가져와야 합니다.

인앱 메시지는 표시 전 캠페인 자격 재평가가 선택되어 있거나, 메시지에 다음 Liquid 태그 중 하나라도 포함되어 있는 경우 템플릿 인앱 메시지로 전달됩니다:

• canvas_entry_properties
• connected_content
• {sms.${*}}와 같은 SMS 변수
• catalog_items
• catalog_selection_items
• event_properties

이 경우 세션 시작 시 기기는 전체 메시지 대신 해당 인앱 메시지의 트리거만 수신합니다. 사용자가 인앱 메시지를 트리거하면, 사용자의 기기가 네트워크 요청을 보내 실제 메시지를 가져옵니다.

참고

기기가 인터넷에 접속할 수 없는 경우 메시지가 전달되지 않습니다. Liquid 로직을 처리하는 데 시간이 너무 오래 걸리면 메시지가 전달되지 않을 수 있습니다.

키-값 페어

Braze에서 Campaign을 생성할 때 키-값 페어를 extras로 설정할 수 있으며, 인앱 메시징 오브젝트가 이를 사용하여 앱으로 데이터를 전송할 수 있습니다.

• 웹
• android
• swift

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import * as braze from "@braze/web-sdk";

braze.subscribeToInAppMessage(function(inAppMessage) {
  // control group messages should always be "shown"
  // this will log an impression and not show a visible message
  if (inAppMessage instanceof braze.ControlMessage) {
    return braze.showInAppMessage(inAppMessage);
  }


  if (inAppMessage instanceof braze.InAppMessage) {
    const extras = inAppMessage.extras;
    if (extras) {
      for (const key in extras) {
        console.log("key: " + key + ", value: " + extras[key]);
      }
    }
  }
  braze.showInAppMessage(inAppMessage);
});

• java
• kotlin

1
Map<String, String> getExtras()

1
extras: Map<String, String>

팁

자세한 내용은 KDoc을 참조하세요.

다음 예제에서는 커스텀 로직을 사용하여 extras의 키-값 페어를 기반으로 인앱 메시지의 표시 방식을 설정합니다. 전체 커스터마이징 예제는 샘플 앱을 확인하세요.

• swift
• objective-c

1
2
3
4
let customization = message.extras["custom-display"] as? String
if customization == "colorful-slideup" {
  // Perform your custom logic.
}

1
2
3
4
5
6
if ([message.extras[@"custom-display"] isKindOfClass:[NSString class]]) {
  NSString *customization = message.extras[@"custom-display"];
  if ([customization isEqualToString:@"colorful-slideup"]) {
    // Perform your custom logic.
  }
}

자동 트리거 비활성화

기본적으로 인앱 메시지는 자동으로 트리거됩니다. 이를 비활성화하려면 다음을 수행합니다.

• 웹
• android
• swift
• flutter
• unity

로딩 스니펫에서 braze.automaticallyShowInAppMessages() 호출을 제거한 다음, 인앱 메시지를 표시하거나 표시하지 않도록 처리하는 커스텀 로직을 만듭니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
braze.subscribeToInAppMessage(function(inAppMessage) {
  // control group messages should always be "shown"
  // this will log an impression and not show a visible message

  if (inAppMessage.isControl) { // v4.5.0+, otherwise use  `inAppMessage instanceof braze.ControlMessage`
     return braze.showInAppMessage(inAppMessage);
  }

  // Display the in-app message. You could defer display here by pushing this message to code within your own application.
  // If you don't want to use the display capabilities in Braze, you could alternatively pass the in-app message to your own display code here.

  if ( should_show_the_message_according_to_your_custom_logic ) {
      braze.showInAppMessage(inAppMessage);
  } else {
      // do nothing
  }
});

중요

braze.automaticallyShowInAppMessages()를 제거하지 않고 braze.showInAppMessage를 호출하면 메시지가 두 번 표시될 수 있습니다.

메시지 타이밍에 대한 더 고급 제어(트리거된 메시지의 지연 및 복원 포함)에 대해서는 튜토리얼: 트리거된 메시지 지연 및 복원을 참조하세요.

1. IInAppMessageManagerListener를 구현하여 커스텀 리스너를 설정합니다.
2. beforeInAppMessageDisplayed() 메서드를 업데이트하여 InAppMessageOperation.DISCARD를 반환하도록 합니다.

메시지 타이밍에 대한 더 고급 제어(나중에 표시하거나 다시 대기열에 추가하는 것 포함)에 대해서는 메시지 커스터마이징 페이지를 참조하세요.

1. 앱에서 BrazeInAppMessageUIDelegate 델리게이트를 구현합니다. 전체 안내는 튜토리얼: 인앱 메시지 UI를 참조하세요.
2. inAppMessage(_:displayChoiceForMessage:) 델리게이트 메서드를 업데이트하여 .discard를 반환하도록 합니다.

메시지 타이밍에 대한 더 고급 제어(트리거된 메시지의 지연 및 복원 포함)에 대해서는 튜토리얼: 트리거된 메시지 지연 및 복원을 참조하세요.

1. 버전 2.2.0 이상에서 기본적으로 활성화되어 있는 자동 통합 이니셜라이저를 사용하고 있는지 확인합니다.
2. braze.xml 파일에 다음 줄을 추가하여 인앱 메시지 작업 기본값을 DISCARD로 설정합니다.

   1
    <string name="com_braze_flutter_automatic_integration_iam_operation">DISCARD</string>
   

• android
• ios

Android의 경우, Braze 구성 편집기에서 Automatically Display In-App Messages를 선택 해제합니다. 또는 Unity 프로젝트의 braze.xml에서 com_braze_inapp_show_inapp_messages_automatically를 false로 설정할 수 있습니다.

초기 인앱 메시지 표시 작업은 Braze 구성에서 “In App Message Manager Initial Display Operation”을 사용하여 설정할 수 있습니다.

iOS의 경우, Braze 구성 편집기에서 게임 오브젝트 리스너를 설정하고 Braze Displays In-App Messages가 선택되어 있지 않은지 확인합니다.

초기 인앱 메시지 표시 작업은 Braze 구성에서 “In App Message Manager Initial Display Operation”을 사용하여 설정할 수 있습니다.

하나의 세션에서 두 개의 인앱 메시지 연결하기

세션 시작 시 인앱 메시지를 트리거한 다음, 첫 번째 메시지에서 버튼을 누른 후 두 번째 인앱 메시지를 트리거할 수 있습니다. 이렇게 하려면 두 번째 메시지를 트리거할 버튼 클릭에 대해 커스텀 이벤트를 기록합니다. 두 번째 메시지의 트리거는 이미 기기에 존재해야 하며(사용자가 이미 두 번째 메시지의 수신 대상이어야 함), 기기 측에서 발생해야 합니다(Braze SDK는 Braze 서버에서 발생하는 커스텀 속성 변경 사항을 감지하지 못합니다). 인앱 메시지 트리거 간 기본 30초 쿨다운을 변경해야 여러 인앱 메시지를 빠르게 연속으로 표시할 수 있습니다. 플랫폼별 설정 방법은 기본 사용량 제한 재정의하기를 참조하세요.

기본 사용량 제한 재정의

기본적으로 SDK는 트리거된 인앱 메시지의 사용량 제한을 30초에 한 번으로 설정합니다. 이를 재정의하려면 Braze 인스턴스가 초기화되기 전에 구성 파일에 다음 속성을 추가하세요. 이 값은 새로운 사용량 제한(초 단위)으로 사용됩니다.

프로덕션 앱에서는 이 값을 10초 미만으로 설정하지 마세요. 사용자가 연속적인 인앱 메시지에 압도될 수 있습니다. 테스트 및 샘플 앱 플로우에서는 5초가 일반적인 설정입니다.

테스트 목적으로 이 간격을 0으로 설정할 수 있습니다. 그러나 0초 간격이 여러 인앱 메시지를 동시에 표시하도록 강제하지는 않습니다. 하나의 인앱 메시지가 이미 표시되고 있는 경우, 현재 메시지가 닫힐 때까지 다른 트리거된 메시지는 표시되지 않습니다.

• 웹
• android
• swift

1
2
// Sets the minimum time interval between triggered in-app messages to 5 seconds instead of the default 30
braze.initialize('YOUR-API-KEY', { minimumIntervalBetweenTriggerActionsInSeconds: 5 })

1
<integer name="com_braze_trigger_action_minimum_time_interval_seconds">5</integer>

1
2
3
4
5
6
7
8
let configuration = Braze.Configuration(
  apiKey: "YOUR-APP-IDENTIFIER-API-KEY",
  endpoint: "YOUR-BRAZE-ENDPOINT"
)
// Sets the minimum trigger time interval to 5 seconds
configuration.triggerMinimumTimeInterval = 5
let braze = Braze(configuration: configuration)
AppDelegate.braze = braze

1
2
3
4
5
6
7
BRZConfiguration *configuration =
    [[BRZConfiguration alloc] initWithApiKey:@"<BRAZE_API_KEY>"
                                    endpoint:@"<BRAZE_ENDPOINT>"];
// Sets the minimum trigger time interval to 5 seconds
configuration.triggerMinimumTimeInterval = 5;
Braze *braze = [BrazePlugin initBraze:configuration];
AppDelegate.braze = braze;

수동으로 메시지 트리거하기

기본적으로 인앱 메시지는 SDK가 커스텀 이벤트를 기록할 때 자동으로 트리거됩니다. 그러나 이 외에도 다음 메서드를 사용하여 수동으로 메시지를 트리거할 수 있습니다.

서버 측 이벤트 사용

• web
• android
• swift

현재 웹 Braze SDK는 서버 측 이벤트를 사용한 수동 메시지 트리거를 지원하지 않습니다.

서버에서 전송된 이벤트를 사용하여 인앱 메시지를 트리거하려면, 기기에 사일런트 푸시 알림을 보내 커스텀 푸시 콜백이 SDK 기반 이벤트를 기록하도록 합니다. 이 이벤트가 사용자에게 표시되는 인앱 메시지를 트리거합니다.

1단계: 사일런트 푸시를 수신할 푸시 콜백 생성

특정 사일런트 푸시 알림을 수신하도록 커스텀 푸시 콜백을 등록합니다. 자세한 내용은 푸시 알림 설정을 참조하세요.

인앱 메시지가 전달되려면 두 개의 이벤트가 기록됩니다. 하나는 서버에서, 다른 하나는 커스텀 푸시 콜백 내에서 기록됩니다. 동일한 이벤트가 중복되지 않도록 하려면, 푸시 콜백 내에서 기록되는 이벤트는 서버에서 전송된 이벤트와 동일한 이름이 아닌 “인앱 메시지 트리거 이벤트”와 같은 일반적인 명명 규칙을 따라야 합니다. 이렇게 하지 않으면 단일 사용자 액션에 대해 중복 이벤트가 기록되어 세분화 및 사용자 데이터에 영향을 줄 수 있습니다.

• java
• kotlin

1
2
3
4
5
6
7
8
9
10
11
Braze.getInstance(context).subscribeToPushNotificationEvents(event -> {
  final Bundle kvps = event.getNotificationPayload().getBrazeExtras();
  if (kvps.containsKey("IS_SERVER_EVENT")) {
    BrazeProperties eventProperties = new BrazeProperties();

    // The campaign name is a string extra that clients can include in the push
    String campaignName = kvps.getString("CAMPAIGN_NAME");
    eventProperties.addProperty("campaign_name", campaignName);
    Braze.getInstance(context).logCustomEvent("IAM Trigger", eventProperties);
  }
});

1
2
3
4
5
6
7
8
9
10
11
Braze.getInstance(applicationContext).subscribeToPushNotificationEvents { event ->
    val kvps = event.notificationPayload.brazeExtras
    if (kvps.containsKey("IS_SERVER_EVENT")) {
        val eventProperties = BrazeProperties()

        // The campaign name is a string extra that clients can include in the push
        val campaignName = kvps.getString("CAMPAIGN_NAME")
        eventProperties.addProperty("campaign_name", campaignName)
        Braze.getInstance(applicationContext).logCustomEvent("IAM Trigger", eventProperties)
    }
}

2단계: 푸시 Campaign 생성

서버에서 전송된 이벤트를 통해 트리거되는 사일런트 푸시 Campaign을 생성합니다.

푸시 Campaign에는 이 푸시 Campaign이 SDK 커스텀 이벤트를 기록하기 위해 전송되었음을 나타내는 키-값 페어 추가 항목이 포함되어야 합니다. 이 이벤트는 인앱 메시지를 트리거하는 데 사용됩니다.

앞서 작성한 푸시 콜백 샘플 코드는 키-값 페어를 인식하고 적절한 SDK 커스텀 이벤트를 기록합니다.

“인앱 메시지 트리거” 이벤트에 이벤트 속성정보를 첨부하려면, 푸시 페이로드의 키-값 페어에 이를 전달하면 됩니다. 이 예시에서는 후속 인앱 메시지의 캠페인 이름이 포함되었습니다. 커스텀 푸시 콜백은 커스텀 이벤트를 기록할 때 이벤트 속성정보의 매개변수로 해당 값을 전달할 수 있습니다.

3단계: 인앱 메시지 Campaign 생성

Braze 대시보드에서 사용자에게 표시되는 인앱 메시지 Campaign을 생성합니다. 이 Campaign은 실행 기반 전달이어야 하며, 커스텀 푸시 콜백 내에서 기록된 커스텀 이벤트로부터 트리거되어야 합니다.

다음 예시에서는 초기 사일런트 푸시의 일부로 이벤트 속성정보를 전송하여 트리거할 특정 인앱 메시지가 구성되었습니다.

앱이 포그라운드에 있지 않을 때 서버에서 전송된 이벤트가 기록되면, 이벤트는 기록되지만 인앱 메시지는 표시되지 않습니다. 애플리케이션이 포그라운드에 올 때까지 이벤트를 지연시키려면, 커스텀 푸시 수신기에 앱이 포그라운드에 진입할 때까지 이벤트를 무시하거나 지연시키는 확인 로직을 포함해야 합니다.

1단계: 사일런트 푸시 및 키-값 페어 처리

다음 함수를 구현하고 application(_:didReceiveRemoteNotification:fetchCompletionHandler:) 메서드 내에서 호출합니다:

• swift
• objective-c

1
2
3
4
5
6
func handleExtras(userInfo: [AnyHashable : Any]) {
  print("A push was received")
  if userInfo != nil && (userInfo["IS_SERVER_EVENT"] as? String) != nil && (userInfo["CAMPAIGN_NAME"] as? String) != nil {
    AppDelegate.braze?.logCustomEvent("IAM Trigger", properties: ["campaign_name": userInfo["CAMPAIGN_NAME"]])
  }
}

1
2
3
4
5
6
- (void)handleExtrasFromPush:(NSDictionary *)userInfo {
  NSLog(@"A push was received.");
  if (userInfo !=nil && userInfo[@"IS_SERVER_EVENT"] !=nil && userInfo[@"CAMPAIGN_NAME"]!=nil) {
    [AppDelegate.braze logCustomEvent:@"IAM Trigger" properties:@{@"campaign_name": userInfo[@"CAMPAIGN_NAME"]}];
  }
};

사일런트 푸시가 수신되면, SDK에서 기록한 “인앱 메시지 트리거” 이벤트가 고객 프로필에 기록됩니다.

중요

푸시 메시지를 사용하여 SDK에서 기록하는 커스텀 이벤트를 기록하므로, Braze는 이 솔루션을 활성화하기 위해 각 사용자에 대한 푸시 토큰을 저장해야 합니다. iOS 사용자의 경우, Braze는 사용자가 OS의 푸시 프롬프트를 받은 시점부터만 토큰을 저장합니다. 그 이전에는 사용자에게 푸시로 도달할 수 없으며, 위의 솔루션을 사용할 수 없습니다.

2단계: 사일런트 푸시 Campaign 생성

서버에서 전송된 이벤트를 통해 트리거되는 사일런트 푸시 Campaign을 생성합니다.

푸시 Campaign에는 이 푸시 Campaign이 SDK 커스텀 이벤트를 기록하기 위해 전송되었음을 나타내는 키-값 페어 추가 항목이 포함되어야 합니다. 이 이벤트는 인앱 메시지를 트리거하는 데 사용됩니다.

application(_:didReceiveRemoteNotification:fetchCompletionHandler:) 메서드 내의 코드는 IS_SERVER_EVENT 키를 확인하고, 이 키가 존재하면 SDK 커스텀 이벤트를 기록합니다.

푸시 페이로드의 키-값 페어 추가 항목 내에 원하는 값을 전송하여 이벤트 이름이나 이벤트 속성정보를 변경할 수 있습니다. 커스텀 이벤트를 기록할 때, 이러한 추가 항목을 이벤트 이름의 매개변수 또는 이벤트 속성정보로 사용할 수 있습니다.

3단계: 인앱 메시지 Campaign 생성

Braze 대시보드에서 사용자에게 표시되는 인앱 메시지 Campaign을 생성합니다. 이 Campaign은 실행 기반 전달이어야 하며, application(_:didReceiveRemoteNotification:fetchCompletionHandler:) 메서드 내에서 기록된 커스텀 이벤트로부터 트리거되어야 합니다.

다음 예시에서는 초기 사일런트 푸시의 일부로 이벤트 속성정보를 전송하여 트리거할 특정 인앱 메시지가 구성되었습니다.

참고

이러한 인앱 메시지는 애플리케이션이 포그라운드에 있을 때 사일런트 푸시가 수신된 경우에만 트리거됩니다.

사전 정의된 메시지 표시

사전 정의된 인앱 메시지를 수동으로 표시하려면 다음 메서드를 사용합니다:

• web
• android
• swift

1
BrazeInAppMessageManager.getInstance().addInAppMessage(inAppMessage);

1
BrazeInAppMessageManager.getInstance().addInAppMessage(inAppMessage)

1
2
3
if let inAppMessage = AppDelegate.braze?.inAppMessagePresenter?.nextAvailableMessage() {
  AppDelegate.braze?.inAppMessagePresenter?.present(message: inAppMessage)
}

실시간으로 메시지 표시

대시보드에서 사용할 수 있는 것과 동일한 커스터마이징 옵션을 사용하여 로컬 인앱 메시지를 실시간으로 생성하고 표시할 수도 있습니다. 이를 위해:

• web
• android
• swift
• unity

1
2
3
4
  // Displays a slideup type in-app message.
  var message = new braze.SlideUpMessage("Welcome to Braze! This is an in-app message.");
  message.slideFrom = braze.InAppMessage.SlideFrom.TOP;
  braze.showInAppMessage(message);

• java
• kotlin

1
2
3
// Initializes a new slideup type in-app message and specifies its message.
InAppMessageSlideup inAppMessage = new InAppMessageSlideup();
inAppMessage.setMessage("Welcome to Braze! This is a slideup in-app message.");

1
2
3
// Initializes a new slideup type in-app message and specifies its message.
val inAppMessage = InAppMessageSlideup()
inAppMessage.message = "Welcome to Braze! This is a slideup in-app message."

중요

소프트 키보드가 화면에 표시되어 있을 때는 인앱 메시지를 표시하지 마세요. 이 상황에서는 렌더링이 정의되지 않습니다.

inAppMessagePresenter에서 present(message:) 메서드를 수동으로 호출합니다. 예시:

• swift
• objective-c

1
2
3
4
let customInAppMessage = Braze.InAppMessage.slideup(
  .init(message: "YOUR_CUSTOM_SLIDEUP_MESSAGE", slideFrom: .bottom, themes: .defaults)
)
AppDelegate.braze?.inAppMessagePresenter?.present(message: customInAppMessage)

1
2
3
4
5
6
7
8
9
BRZInAppMessageRaw *customInAppMessage = [[BRZInAppMessageRaw alloc] init];
customInAppMessage.type = BRZInAppMessageRawTypeSlideup;
customInAppMessage.message = @"YOUR_CUSTOM_SLIDEUP_MESSAGE";
customInAppMessage.slideFrom = BRZInAppMessageRawSlideFromBottom;
customInAppMessage.themes = @{
  @"light": BRZInAppMessageRawTheme.defaultLight,
  @"dark": BRZInAppMessageRawTheme.defaultDark
};
[AppDelegate.braze.inAppMessagePresenter presentMessage:customInAppMessage];

참고

자체 인앱 메시지를 생성하면 모든 분석 추적이 해제되며, message.context를 사용하여 클릭 및 노출 횟수 로깅을 수동으로 처리해야 합니다.

스택에서 다음 메시지를 표시하려면 DisplayNextInAppMessage() 메서드를 사용합니다. 인앱 메시지 표시 액션으로 DISPLAY_LATER 또는 BrazeUnityInAppMessageDisplayActionType.IAM_DISPLAY_LATER가 선택된 경우 메시지가 이 스택에 저장됩니다.

1
Appboy.AppboyBinding.DisplayNextInAppMessage();

인앱 메시지 지연 원인

세션 시작 후 몇 초 뒤에 인앱 메시지 Campaign을 수신하는 경우, 다음과 같은 원인으로 지연이 발생할 수 있습니다:

• Campaign 트리거 지연
• 커스터마이징
• 예상보다 늦게 기록되는 트리거 이벤트(예: templated_iam)

웹용 이탈 의도 메시지

이탈 의도 메시지는 방문자가 웹사이트를 떠나기 전에 중요한 정보를 전달하는 데 사용되는 비침습적 인앱 메시지입니다.

웹 SDK에서 이러한 메시지 유형에 대한 트리거를 설정하려면 웹사이트에 이탈 의도 라이브러리(예: ouibounce의 오픈소스 라이브러리)를 구현한 다음, 아래 코드를 사용하여 Braze에서 'exit intent'를 커스텀 이벤트로 기록합니다. 이제 향후 인앱 메시지 캠페인에서 이 메시지 유형을 커스텀 이벤트 트리거로 사용할 수 있습니다.

1
2
3
  var _ouibounce = ouibounce(false, {
    callback: function() { braze.logCustomEvent('exit intent'); }
  });