Content Cards 피드 커스터마이즈

Content Cards 피드는 모바일 또는 웹 애플리케이션에 표시되는 Content Cards의 시퀀스입니다. 이 문서에서는 피드 새로고침 시기 설정, 카드 순서 지정, 여러 피드 관리, “빈 피드” 오류 메시지 등을 구성하는 방법을 다룹니다. 콘텐츠 카드 유형의 전체 목록은 Content Cards 정보를 참조하세요.

세션 생명주기에 대하여

세션은 앱이 실행된 후 Braze SDK가 사용자 활동을 추적하는 기간을 의미합니다. changeUser() 메서드를 호출하여 새로운 세션을 강제로 시작할 수도 있습니다.

• 웹
• android
• swift

기본적으로 세션은 braze.openSession()을 처음 호출할 때 시작됩니다. 세션은 비활동 상태가 30분 이상 지속되지 않는 한 활성 상태를 유지합니다(기본 세션 타임아웃을 변경하거나 사용자가 앱을 닫지 않는 한).

참고

Android용 액티비티 생명주기 콜백을 설정한 경우, Braze는 앱의 각 액티비티에 대해 openSession() 및 closeSession()을 자동으로 호출합니다.

기본적으로 세션은 openSession()이 처음 호출될 때 시작됩니다. 앱이 백그라운드로 전환된 후 다시 포그라운드로 돌아오면, SDK는 세션이 시작된 이후 10초 이상 경과했는지 확인합니다(기본 세션 타임아웃을 변경하지 않는 한). 10초 이상 경과한 경우 새로운 세션이 시작됩니다. 사용자가 앱이 백그라운드에 있는 상태에서 종료하면, 세션 데이터는 사용자가 앱을 다시 열 때까지 Braze에 전송되지 않을 수 있다는 점에 유의하세요.

closeSession()을 호출한다고 해서 세션이 즉시 종료되지는 않습니다. 대신, 사용자가 다른 액티비티를 시작하여 openSession()을 다시 호출하지 않으면 10초 후에 세션이 종료됩니다.

기본적으로 세션은 Braze.init(configuration:)을 호출할 때 시작됩니다. 이는 UIApplicationWillEnterForegroundNotification 알림이 트리거될 때 발생하며, 앱이 포그라운드로 진입했음을 의미합니다.

앱이 백그라운드로 전환되면 UIApplicationDidEnterBackgroundNotification이 트리거됩니다. 앱은 백그라운드에 있는 동안 활성 세션을 유지하지 않습니다. 앱이 포그라운드로 돌아오면, SDK는 세션이 시작된 이후 경과된 시간을 세션 타임아웃과 비교합니다(기본 세션 타임아웃을 변경하지 않는 한). 세션이 시작된 이후의 시간이 타임아웃 기간을 초과하면 새로운 세션이 시작됩니다.

피드 새로 고침

자동 새로 고침

기본적으로 Content Card 피드는 다음과 같은 경우 자동으로 새로 고침됩니다.

• 새 세션이 시작된 경우
• 마지막 새로 고침 후 60초 이상 지난 시점에 기본 Content Card 피드를 닫았다가 다시 연 경우

팁

수동으로 새로 고침하지 않고도 최신 Content Cards를 동적으로 표시하려면 카드를 생성할 때 첫 노출 시를 선택하세요. 이러한 카드는 사용할 수 있게 되면 새로 고침됩니다.

실시간 전달

Braze는 세션 동안 SDK가 유지하는 실시간 연결을 통해 Content Card 업데이트가 발생하는 즉시 기기로 전송합니다. 사용자는 변경 사항을 확인하기 위해 새 세션을 시작하거나 새로 고침을 기다릴 필요가 없습니다. 실시간 전달은 기본 Content Card 피드와 커스텀 Content Card 피드 모두에서 작동합니다.

실시간 전달은 다음 업데이트에 적용됩니다.

• 세션 중에 사용자가 Content Card Campaign의 대상 자격을 얻는 경우
• 사용자가 Canvas의 Content Card 단계로 진행하는 경우
• 사용자의 피드에서 카드가 제거되는 경우
• /messages/send, /campaigns/trigger/send 또는 /canvas/trigger/send 엔드포인트와 같이 API를 통해 카드가 전송되는 경우

실시간 전달을 사용하려면 다음 최소 SDK 버전이 필요합니다.

이전 SDK 버전에서는 계속해서 세션 시작 시와 새로 고침 시에 카드가 도착합니다.

수동 새로 고침

특정 시점에 피드를 수동으로 새로 고침하려면 다음과 같이 하세요.

• web
• android
• swift

1
2
3
4
5

import * as braze from "@braze/web-sdk";

function refresh() {
  braze.requestContentCardsRefresh();
}

1

Braze.getInstance(context).requestContentCardsRefresh();

1

Braze.getInstance(context).requestContentCardsRefresh()

1
2
3

AppDelegate.braze?.contentCards.requestRefresh { result in
  // Implement completion handler
}

1

let contentCards = await AppDelegate.braze?.contentCards.requestRefresh()

1
2
3

[AppDelegate.braze.contentCards requestRefreshWithCompletion:^(NSArray<BRZContentCardRaw *> * contentCards, NSError * error) {
  // Implement completion handler
}];

전체 동기화와 부분 동기화 비교

Braze SDK는 서버에서 Content Cards를 가져올 때 두 가지 유형의 동기화를 사용합니다.

• 전체 동기화: 사용자가 받을 수 있는 모든 Content Cards를 가져옵니다. 전체 동기화는 7일마다 또는 changeUser()가 호출될 때마다 자동으로 실행됩니다.
• 부분 동기화: 마지막 요청 이후의 새 Content Cards만 가져옵니다. 사용자가 받을 수 있는 새 카드가 없으면 응답에서 카드가 0개 반환됩니다. 부분 동기화는 requestContentCardsRefresh()가 호출될 때마다 실행됩니다(단, 마지막 전체 동기화 후 7일이 지난 경우에는 대신 전체 동기화가 트리거됩니다).

부분 동기화는 서버 부하와 기기 배터리 사용량을 줄여 줍니다. 이미 수신된 Content Cards는 SDK에 로컬로 저장되므로, 부분 동기화에서 새 카드가 0개 반환되더라도 사용자는 계속해서 사용 가능한 카드를 볼 수 있습니다.

사용량 제한

Braze는 토큰 버킷 알고리즘을 사용하여 다음과 같은 사용량 제한을 적용합니다.

• 기기당 최대 5회의 새로 고침 호출이 가능하며, 이는 사용자 및 openSession() 호출 간에 공유됩니다.
• 한도에 도달하면 180초(3분)마다 새 호출을 사용할 수 있게 됩니다.
• 시스템은 언제든지 사용할 수 있도록 최대 5회의 호출을 보관합니다.
• 사용량 제한이 적용된 상태에서도 subscribeToContentCards()는 여전히 캐시된 카드를 반환합니다.

중요

Braze SDK는 성능과 안정성을 위해 사용량 제한도 적용합니다. 자동화된 테스트를 실행하거나 수동 QA를 수행할 때 이 점을 유의하세요. 자세한 내용은 Braze SDK 사용량 제한을 참조하세요.

표시되는 카드 순서 사용자 지정

Content Cards가 표시되는 순서를 변경할 수 있습니다. 이를 통해 시간에 민감한 프로모션 등 특정 유형의 콘텐츠에 우선순위를 두어 사용자 경험을 세밀하게 조정할 수 있습니다.

• web
• android
• swift

showContentCards():의 filterFunction 매개변수를 사용하여 피드에 표시되는 Content Cards의 순서를 사용자 지정할 수 있습니다. 예를 들면 다음과 같습니다.

1
2
3

braze.showContentCards(null, (cards) => {
  return sortBrazeCards(cards); // Where sortBrazeCards is your sorting function that returns the sorted card array
});

• android view controller
• jetpack compose

ContentCardsFragment는 IContentCardsUpdateHandler를 사용하여 Content Cards가 피드에 표시되기 전에 정렬이나 수정을 처리합니다. 커스텀 업데이트 핸들러는 ContentCardsFragment에서 setContentCardUpdateHandler를 통해 설정할 수 있습니다.

다음은 기본 IContentCardsUpdateHandler이며, 사용자 지정을 위한 시작점으로 사용할 수 있습니다.

Java 예시 보기

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

public class DefaultContentCardsUpdateHandler implements IContentCardsUpdateHandler {

  // Interface that must be implemented and provided as a public CREATOR
  // field that generates instances of your Parcelable class from a Parcel.
  public static final Parcelable.Creator<DefaultContentCardsUpdateHandler> CREATOR = new Parcelable.Creator<DefaultContentCardsUpdateHandler>() {
    public DefaultContentCardsUpdateHandler createFromParcel(Parcel in) {
      return new DefaultContentCardsUpdateHandler();
    }

    public DefaultContentCardsUpdateHandler[] newArray(int size) {
      return new DefaultContentCardsUpdateHandler[size];
    }
  };

  @Override
  public List<Card> handleCardUpdate(ContentCardsUpdatedEvent event) {
    List<Card> sortedCards = event.getAllCards();
    // Sort by pinned, then by the 'updated' timestamp descending
    // Pinned before non-pinned
    Collections.sort(sortedCards, new Comparator<Card>() {
      @Override
      public int compare(Card cardA, Card cardB) {
        // A displays above B
        if (cardA.getIsPinned() && !cardB.getIsPinned()) {
          return -1;
        }

        // B displays above A
        if (!cardA.getIsPinned() && cardB.getIsPinned()) {
          return 1;
        }

        // At this point, both A & B are pinned or both A & B are non-pinned
        // A displays above B since A is newer
        if (cardA.getUpdated() > cardB.getUpdated()) {
          return -1;
        }

        // B displays above A since A is newer
        if (cardA.getUpdated() < cardB.getUpdated()) {
          return 1;
        }

        // At this point, every sortable field matches so keep the natural ordering
        return 0;
      }
    });

    return sortedCards;
  }

  // Parcelable interface method
  @Override
  public int describeContents() {
    return 0;
  }

  // Parcelable interface method
  @Override
  public void writeToParcel(Parcel dest, int flags) {
    // No state is kept in this class so the parcel is left unmodified
  }
}

Kotlin 예시 보기

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

class DefaultContentCardsUpdateHandler : IContentCardsUpdateHandler {
  override fun handleCardUpdate(event: ContentCardsUpdatedEvent): List<Card> {
    val sortedCards = event.allCards
    // Sort by pinned, then by the 'updated' timestamp descending
    // Pinned before non-pinned
    sortedCards.sortWith(Comparator sort@{ cardA: Card, cardB: Card ->
      // A displays above B
      if (cardA.isPinned && !cardB.isPinned) {
        return@sort -1
      }

      // B displays above A
      if (!cardA.isPinned && cardB.isPinned) {
        return@sort 1
      }

      // At this point, both A & B are pinned or both A & B are non-pinned
      // A displays above B since A is newer
      if (cardA.updated > cardB.updated) {
        return@sort -1
      }

      // B displays above A since A is newer
      if (cardA.updated < cardB.updated) {
        return@sort 1
      }
      0
    })
    return sortedCards
  }

  // Parcelable interface method
  override fun describeContents(): Int {
    return 0
  }

  // Parcelable interface method
  override fun writeToParcel(dest: Parcel, flags: Int) {
    // No state is kept in this class so the parcel is left unmodified
  }

  companion object {
    // Interface that must be implemented and provided as a public CREATOR
    // field that generates instances of your Parcelable class from a Parcel.
    val CREATOR: Parcelable.Creator<DefaultContentCardsUpdateHandler?> = object : Parcelable.Creator<DefaultContentCardsUpdateHandler?> {
      override fun createFromParcel(`in`: Parcel): DefaultContentCardsUpdateHandler? {
        return DefaultContentCardsUpdateHandler()
      }

      override fun newArray(size: Int): Array<DefaultContentCardsUpdateHandler?> {
        return arrayOfNulls(size)
      }
    }
  }
}

팁

ContentCardsFragment 소스는 GitHub에서 확인할 수 있습니다.

Jetpack Compose에서 Content Cards를 필터링하고 정렬하려면 cardUpdateHandler 매개변수를 설정합니다. 예를 들면 다음과 같습니다.

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

ContentCardsList(
    cardUpdateHandler = {
        it.sortedWith { cardA, cardB ->
            // A displays above B
            if (cardA.isPinned && !cardB.isPinned) {
                return@sortedWith -1
            }
            // B displays above A
            if (!cardA.isPinned && cardB.isPinned) {
                return@sortedWith 1
            }
            // At this point, both A & B are pinned or both A & B are non-pinned
            // A displays above B since A is newer
            if (cardA.updated > cardB.updated) {
                return@sortedWith -1
            }
            // B displays above A since A is newer
            if (cardA.updated < cardB.updated) {
                return@sortedWith 1
            }
            0
        }
    }
)

• swift
• objective-c

정적 변수 Attributes.defaults를 직접 수정하여 카드 피드 순서를 사용자 지정할 수 있습니다.

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

var attributes = BrazeContentCardUI.ViewController.Attributes.defaults
attributes.transform = { cards in
    cards.sorted {
        if $0.pinned && !$1.pinned {
            return true
        } else if !$0.pinned && $1.pinned {
            return false
        } else {
            return $0.createdAt > $1.createdAt
        }
    }
}
let viewController = BrazeContentCardUI.ViewController(braze: AppDelegate.braze, attributes: attributes)

Objective-C에서는 BrazeContentCardUI.ViewController.Attributes를 통한 사용자 지정을 사용할 수 없습니다.

“빈 피드” 메시지 커스텀하기

사용자가 Content Cards를 받을 자격이 없으면 SDK가 “We have no updates. Please check again later.”라는 “빈 피드” 오류 메시지를 표시합니다. 이 “빈 피드” 오류 메시지는 다음과 같이 커스텀할 수 있습니다.

• web
• android
• swift

웹 SDK는 “빈 피드” 문구를 프로그래밍 방식으로 교체하는 기능을 지원하지 않습니다. 피드가 표시될 때마다 문구를 교체할 수도 있지만, 피드를 새로 고치는 데 시간이 걸릴 수 있어 빈 피드 텍스트가 바로 표시되지 않으므로 권장하지 않습니다.

• android view system
• jetpack compose

ContentCardsFragment가 사용자에게 Content Cards를 받을 자격이 없다고 판단하면 빈 피드 오류 메시지를 표시합니다.

특수 어댑터인 EmptyContentCardsAdapter가 표준 ContentCardAdapter를 대체하여 이 오류 메시지를 표시합니다. 커스텀 메시지 자체를 설정하려면 문자열 리소스 com_braze_feed_empty를 재정의하세요.

이 메시지를 표시하는 데 사용되는 스타일은 Braze.ContentCardsDisplay.Empty에서 확인할 수 있으며, 다음 코드 스니펫에도 나와 있습니다.

1
2
3
4
5
6
7
8
9

<style name="Braze.ContentCardsDisplay.Empty">
  <item name="android:lineSpacingExtra">1.5dp</item>
  <item name="android:text">@string/com_braze_feed_empty</item>
  <item name="android:textColor">@color/com_braze_content_card_empty_text_color</item>
  <item name="android:textSize">18.0sp</item>
  <item name="android:gravity">center</item>
  <item name="android:layout_height">match_parent</item>
  <item name="android:layout_width">match_parent</item>
</style>

콘텐츠 카드 스타일 요소 커스텀에 대한 자세한 내용은 스타일 커스텀하기를 참조하세요.

Jetpack Compose로 “빈 피드” 오류 메시지를 커스텀하려면 ContentCardsList에 emptyString을 전달하면 됩니다. 또한 ContentCardListStyling에 emptyTextStyle을 전달하여 이 메시지를 더 세밀하게 커스텀할 수 있습니다.

1
2
3
4
5
6

ContentCardsList(
    emptyString = "No messages today",
    style = ContentCardListStyling(
        emptyTextStyle = TextStyle(...)
    )
)

대신 표시하고 싶은 Composable이 있다면 ContentCardsList에 emptyComposable을 전달하면 됩니다. emptyComposable을 지정하면 emptyString은 사용되지 않습니다.

1
2
3
4
5
6
7
8

ContentCardsList(
    emptyComposable = {
        Image(
            painter = painterResource(id = R.drawable.noMessages),
            contentDescription = "No messages"
        )
    }
)

• swift
• objective-c

관련 Attributes를 설정하여 뷰 컨트롤러의 빈 상태를 커스텀하세요.

1
2
3
4

var attributes = BrazeContentCardUI.ViewController.Attributes.defaults
attributes.emptyStateMessage = "This is a custom empty state message"
attributes.emptyStateMessageFont = .preferredFont(forTextStyle: .title1)
attributes.emptyStateMessageColor = .secondaryLabel

앱의 ContentCardsLocalizable.strings 파일에서 현지화 가능한 콘텐츠 카드 문자열을 재정의하여 빈 콘텐츠 카드 피드에 자동으로 표시되는 문구를 변경하세요.

참고

다른 로캘 언어로 이 메시지를 업데이트하려면 Resources 폴더 구조에서 해당 언어를 찾아 ContentCardsLocalizable.strings 문자열을 확인하세요.

여러 피드 구현하기

앱에서 Content Cards를 필터링하여 특정 카드만 표시할 수 있으므로, 다양한 사용 사례에 맞춰 여러 개의 Content Card 피드를 운영할 수 있습니다. 예를 들어 트랜잭션 피드와 마케팅 피드를 함께 유지할 수 있습니다. 이렇게 하려면 Braze 대시보드에서 키-값 페어를 설정하여 Content Cards의 카테고리를 구분하세요. 그런 다음 앱이나 사이트에서 이러한 유형의 Content Cards를 서로 다르게 처리하는 피드를 만들어, 일부 유형은 걸러내고 나머지는 표시합니다.

1단계: 카드에 키-값 페어 설정하기

콘텐츠 카드 캠페인을 만들 때 각 카드에 키-값 페어 데이터를 설정합니다. 이 키-값 페어를 사용해 카드를 분류하게 됩니다. 키-값 페어는 카드 데이터 모델의 extras 속성정보에 저장됩니다.

이 예시에서는 카드를 어느 Content Card 피드에 표시할지 지정하는 feed_type 키로 키-값 페어를 설정합니다. 값은 home_screen 또는 marketing처럼 사용하려는 커스텀 피드의 이름이 됩니다.

2단계: Content Cards 필터링하기

키-값 페어를 할당했다면, 표시하려는 카드는 보여주고 다른 유형의 카드는 걸러내는 로직으로 피드를 만드세요. 이 예시에서는 feed_type: "Transactional" 키-값 페어가 일치하는 카드만 표시합니다.

• web
• android
• swift

1
2
3
4
5
6
7
8
9

/**
 * @param {String} feed_type - value of the "feed_type" KVP to filter
 */
function showCardsByFeedType(feed_type) {
  braze.showContentCards(null, function(cards) {
    return cards.filter((card) => card.extras["feed_type"] === feed_type);
  });
}

1
2
3
4

// show the "Transactional" feed when this button is clicked
document.getElementById("show-transactional-feed").onclick = function() {
  showCardsByFeedType("Transactional");
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

private IContentCardsUpdateHandler getUpdateHandlerForFeedType(final String desiredFeedType) {
  return new IContentCardsUpdateHandler() {
    @Override
    public List<Card> handleCardUpdate(ContentCardsUpdatedEvent event) {
      // Use the default card update handler for a first
      // pass at sorting the cards. This is not required
      // but is done for convenience.
      final List<Card> cards = new DefaultContentCardsUpdateHandler().handleCardUpdate(event);

      final Iterator<Card> cardIterator = cards.iterator();
      while (cardIterator.hasNext()) {
        final Card card = cardIterator.next();

        // Make sure the card has our custom KVP
        // from the dashboard with the key "feed_type"
        if (card.getExtras().containsKey("feed_type")) {
          final String feedType = card.getExtras().get("feed_type");
          if (!desiredFeedType.equals(feedType)) {
            // The card has a feed type, but it doesn't match
            // our desired feed type, remove it.
            cardIterator.remove();
          }
        } else {
          // The card doesn't have a feed
          // type at all, remove it
          cardIterator.remove();
        }
      }

      // At this point, all of the cards in this list have
      // a feed type that explicitly matches the value we put
      // in the dashboard.
      return cards;
    }
  };
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

private fun getUpdateHandlerForFeedType(desiredFeedType: String): IContentCardsUpdateHandler {
  return IContentCardsUpdateHandler { event ->
    // Use the default card update handler for a first
    // pass at sorting the cards. This is not required
    // but is done for convenience.
    val cards = DefaultContentCardsUpdateHandler().handleCardUpdate(event)

    val cardIterator = cards.iterator()
    while (cardIterator.hasNext()) {
      val card = cardIterator.next()

      // Make sure the card has our custom KVP
      // from the dashboard with the key "feed_type"
      if (card.extras.containsKey("feed_type")) {
        val feedType = card.extras["feed_type"]
        if (desiredFeedType != feedType) {
          // The card has a feed type, but it doesn't match
          // our desired feed type, remove it.
          cardIterator.remove()
        }
      } else {
        // The card doesn't have a feed
        // type at all, remove it
        cardIterator.remove()
      }
    }

    // At this point, all of the cards in this list have
    // a feed type that explicitly matches the value we put
    // in the dashboard.
    cards
  }
}

1
2
3

// We want a Content Cards feed that only shows "Transactional" cards.
ContentCardsFragment customContentCardsFragment = new ContentCardsFragment();
customContentCardsFragment.setContentCardUpdateHandler(getUpdateHandlerForFeedType("Transactional"));

1
2
3

// We want a Content Cards feed that only shows "Transactional" cards.
val customContentCardsFragment = ContentCardsFragment()
customContentCardsFragment.contentCardUpdateHandler = getUpdateHandlerForFeedType("Transactional")

1
2
3
4
5
6
7

ContentCardsList(
     cardUpdateHandler = {
         it.filter { card ->
             card.extras["feed_type"] == "Transactional"
         }
     }
 )

1
2

// Filter cards by the `Transactional` feed type based on your key-value pair.
let transactionalCards = cards.filter { $0.extras["feed_type"] as? String == "Transactional" }

1
2
3
4
5
6
7

var attributes = BrazeContentCardUI.ViewController.Attributes.defaults
attributes.transform = { cards in
  cards.filter { $0.extras["feed_type"] as? String == "Transactional" }
}

// Pass your attributes containing the transformed cards to the Content Card UI.
let viewController = BrazeContentCardUI.ViewController(braze: AppDelegate.braze, attributes: attributes)

1
2
3
4
5
6
7

// Filter cards by the `Transactional` feed type based on your key-value pair.
NSMutableArray<BRZContentCardRaw *> *transactionalCards = [[NSMutableArray alloc] init];
for (BRZContentCardRaw *card in AppDelegate.braze.contentCards.cards) {
  if ([card.extras[@"feed_type"] isEqualToString:@"Transactional"]) {
    [transactionalCards addObject:card];
  }
}