Pushwoosh Inbox UI Android 설정하기

Pushwoosh Inbox UI는 Pushwoosh 받은 편지함 백엔드 위에 바로 사용할 수 있는 Android 받은 편지함 화면(“종 모양 아이콘” 앱 받은 편지함)을 제공합니다. 5가지 카드 유형 중 하나로 메시지를 렌더링하고, 인라인 CTA 버튼을 지원하며, XML 속성이나 코드를 통해 스타일을 사용자 정의할 수 있습니다.

전제 조건

기본 Pushwoosh Android SDK가 이미 통합되어 푸시를 보내고 있어야 합니다.
앱 모듈에서 Kotlin 지원 (apply plugin: 'kotlin-android').

라이브러리 추가

Kotlin 플러그인과 두 개의 Pushwoosh 모듈을 앱의 build.gradle에 추가합니다:

apply plugin: 'kotlin-android'

dependencies {
    implementation 'com.pushwoosh:pushwoosh-inbox:6.+'
    implementation 'com.pushwoosh:pushwoosh-inbox-ui:6.+'
}

pushwoosh-inbox와 pushwoosh-inbox-ui를 기존 com.pushwoosh:pushwoosh 종속성과 동일한 버전으로 고정하세요. +를 현재 Pushwoosh Android SDK 버전으로 교체하세요.

앱에서 코드 축소를 위해 ProGuard를 사용하는 경우, 받은 편지함 플러그인 클래스를 유지하세요:

-keep public class com.pushwoosh.inbox.PushwooshInboxPlugin {
 *;
}

받은 편지함 표시

받은 편지함을 독립 실행형 화면으로 표시하거나 자체 레이아웃 내에 프래그먼트로 포함할 수 있습니다.

액티비티로:

startActivity(Intent(this, InboxActivity::class.java))

프래그먼트로:

supportFragmentManager.beginTransaction()
    .replace(R.id.inboxContainer, PushwooshInboxUi.createInboxFragment())
    .commitAllowingStateLoss()

카드 유형

Inbox UI는 메시지당 카드 유형을 확인합니다. 확인자는 SDK가 actionParams 아래에 전달하는 푸시 페이로드의 data 객체에서 displayType을 읽습니다. 알려진 카드 유형을 이름으로 지정하는 displayType은 항상 해당 유형을 렌더링하며, 유형의 필수 필드가 누락된 경우에만 classic으로 대체됩니다. 이 확인 과정은 아래의 휴리스틱 설정에 의존하지 않습니다.

displayType이 없는 경우, 이미지/텍스트 휴리스틱을 선택하지 않으면 메시지는 일반 행으로 렌더링됩니다:

PushwooshInboxStyle.richCardsHeuristicEnabled = true

휴리스틱이 켜져 있으면, 제목이 없는 이미지는 banner를, 제목과 본문이 있는 이미지는 captioned를 렌더링하며, 그 외의 모든 것은 classic으로 대체됩니다.

`displayType`	모양	필수 페이로드 필드	대체 유형
`banner`	전체 이미지, 텍스트 없음	image (메시지 아이콘 또는 `data.attachment`)	이미지가 없을 때 `classic`
`captioned`	상단에 이미지, 하단에 제목 + 본문	image, 메시지 `title` 및 `content`	이미지, 제목 또는 본문이 없을 때 `classic`
`classic`	아이콘 + 제목 + 본문	— (제목, 본문, 아이콘 필요)	—
`carousel`	스와이프 가능한 다중 이미지 갤러리	메시지 `title` 및 `content`, `data.carousel` (슬라이드 1–5개)	슬라이드나 제목/본문이 없을 때 `classic`
`video`	재생 배지가 있는 포스터, 탭하면 전체 화면 플레이어	`data.video` (`url` + 선택적 `poster`)	설명자가 없을 때 `classic`

iOS InboxKit의 Apple Wallet 카드는 Android에 해당하는 기능이 없습니다. displayType: "wallet"이 있는 메시지는 Android에서 항상 classic으로 렌더링됩니다.

Carousel 카드

슬라이드는 data.carousel에 있습니다. 각 슬라이드에는 image가 필요합니다. title(캡션 오버레이)과 url(탭 시 열림)은 선택 사항입니다. 이미지가 없는 슬라이드는 삭제되며, 최대 5개의 슬라이드가 표시됩니다.

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "content": "Swipe through this week's drops",
      "inbox_days": 7,
      "data": {
        "displayType": "carousel",
        "carousel": [
          { "image": "https://cdn.example.com/inbox/1.jpg", "title": "New in", "url": "myapp://product/1" },
          { "image": "https://cdn.example.com/inbox/2.jpg", "title": "On sale", "url": "myapp://product/2" }
        ]
      },
      "platforms": [3]
    }]
  }
}

Video 카드

설명자는 data.video에 있습니다: url은 필수이며, poster는 선택적인 미리보기 이미지입니다. 포스터를 탭하면 전체 화면 플레이어가 열립니다.

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "content": "Tap to play",
      "inbox_days": 7,
      "data": {
        "displayType": "video",
        "video": {
          "url": "https://cdn.example.com/inbox/clip.mp4",
          "poster": "https://cdn.example.com/inbox/poster.jpg"
        }
      },
      "platforms": [3]
    }]
  }
}

메시지에서 사용자 정의 데이터 읽기

푸시를 받은 편지함에 표시하려면 Messages API createMessage 요청에 inbox_image, inbox_date 또는 inbox_days가 포함되어야 합니다. 이러한 필드 중 하나가 없으면 푸시는 일반 알림으로 전달되며 받은 편지함 피드에 도달하지 않습니다. 자유 형식의 사용자 정의 데이터는 data 아래에 있으며, SDK는 이를 InboxMessage의 actionParams로 노출합니다:

PushwooshInboxUi.onMessageClickListener = OnInboxMessageClickListener { message ->
    val params = message.actionParams?.let { JSONObject(it) }
    val promoId = params?.optString("promo_id")
    if (!promoId.isNullOrEmpty()) {
        navigateToPromo(promoId)
    }
}

인라인 CTA 버튼 추가

메시지는 data.buttons 내에 인라인 클릭 유도(call-to-action) 버튼을 포함할 수 있습니다:

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "content": "Tap a button to claim or save",
      "inbox_image": "https://cdn.example.com/inbox/promo.png",
      "inbox_days": 7,
      "data": {
        "displayType": "captioned",
        "promo_id": "SUMMER2026",
        "buttons": [
          { "title": "Claim", "url": "https://example.com/promo/SUMMER2026" },
          { "title": "Read",  "action": "markRead" },
          { "title": "Save",  "action": "custom", "tag": "save_promo" }
        ]
      },
      "platforms": [3]
    }]
  }
}

각 버튼에는 title이 필요합니다. 확인은 다음 우선순위를 따릅니다:

action이 dismiss 또는 markRead(대소문자 구분 없음)로 설정되면 해당 작업을 실행합니다.
그렇지 않으면, 비어 있지 않고 파싱 가능한 url은 openURL 작업으로 확인됩니다.
그렇지 않으면, 탭은 사용자 정의 작업으로 확인되며, 버튼 객체의 모든 추가 키는 페이로드로 리스너에 전달됩니다.

PushwooshInboxUi.onButtonClickListener에서 탭을 가로챕니다. SDK가 버튼의 기본 작업을 수행하도록 하려면 true를 반환하고, 이를 억제하려면 false를 반환합니다:

PushwooshInboxUi.onButtonClickListener = OnInboxButtonClickListener { message, button ->
    when (val action = button.action) {
        is InboxCardButton.Action.OpenUrl -> true
        InboxCardButton.Action.Dismiss, InboxCardButton.Action.MarkRead -> true
        is InboxCardButton.Action.Custom -> {
            when (action.payload.optString("tag")) {
                "save_promo" -> saveCurrentPromoLocally(message)
            }
            true
        }
    }
}

스타일 사용자 정의

PushwooshInboxStyle을 통해 코드에서 색상, 글꼴, 비어 있거나 오류 상태를 설정합니다:

PushwooshInboxStyle.accentColor = ContextCompat.getColor(this, R.color.brand_accent)
PushwooshInboxStyle.titleColor = ContextCompat.getColor(this, R.color.brand_title)
PushwooshInboxStyle.listEmptyText = "You have no messages yet"
PushwooshInboxStyle.showToolbar = false

또는 attrs.xml에 나열된 동일한 속성 집합을 테마로 적용할 수도 있습니다: inboxAccentColor, inboxTitleColor, inboxBackgroundColor, inboxDefaultIcon 및 나머지 색상 및 모양 속성. 두 가지 접근 방식과 전체 샘플 앱은 pushwoosh-inbox-ui-android-sdk InboxSample 저장소에 있습니다.

읽지 않은 메시지 배지

PushwooshInbox.unreadMessagesCount { result ->
    if (result.isSuccess) {
        val count = result.data
    } else {
        Log.e("App", "Failed to get unread count", result.exception)
    }
}