📘 Paywall SDK – 사용 설명서 A부터 Z까지 (샘플 JSON 포함)

Source: Dev.to

번역할 텍스트를 제공해 주시면 한국어로 번역해 드리겠습니다.

Paywall SDK – 빠른 참고

대상: Android Kotlin (내부 및 프로덕션 앱)
범위:

• JSON 구성 구조
• 파싱 및 데이터 제공
• UI 렌더링 (Fragment / Dialog)
• 구매, 판매 및 유지 흐름
• 전환 최적화 베스트 프랙티스

아키텍처 흐름

Remote Config / API / Local JSON
        ↓
   PaywallDataProvider
        ↓
    PaywallRepository
        ↓
BasePaywallFragment / BasePaywallDialog
        ↓
   Paywall UI (Full / One / Dialog)

예시 JSON 구성

{
  "uiType": "paywall_full_01",
  "ctaId": 0,
  "enable": true,
  "timesOpen": 0,
  "delayButtonX": 2,
  "timesFree": "1,2,9,10,14",
  "showAdsClose": false,
  "packages": [
    {
      "packageId": "test.com.year.discount",
      "packageIdOrigin": "test.com.yearly",
      "packageType": "yearly",
      "ctaId": 1,
      "isPopular": false,
      "isSelected": false
    },
    {
      "packageId": "test.com.month.discount",
      "packageIdOrigin": "test.com.monthly",
      "packageType": "weekly",
      "ctaId": 3,
      "isPopular": false,
      "isSelected": false
    },
    {
      "packageId": "test.com.week.offer",
      "packageType": "weekly",
      "ctaId": 2,
      "isPopular": true,
      "isSelected": true
    }
  ]
}

필드 정의

페이월‑수준 필드

패키지‑수준 필드

파싱 도우미

fun String.parsePaywall(): PaywallData? {
    if (isBlank()) return null
    return Json {
        ignoreUnknownKeys = true
        explicitNulls = false
    }.decodeFromString(this)
}

JSON을 위한 소스

• Firebase 원격 구성
• 백엔드 API
• 로컬 파일

리포지토리 사용법

override fun getPaywallConfig(placementType: String): PaywallData? {
    return when (placementType) {
        PAYWALL_HOME_ICON -> homeIconJson.parsePaywall()
        PAYWALL_SETTING   -> settingJson.parsePaywall()
        else -> null
    }
}

override fun getRetentionPlacement(current: String): String? {
    return when (current) {
        PAYWALL_HOME_ICON -> PAYWALL_HOME_ICON_SALE
        else -> null
    }
}

paywallRepository.initialize(isDebugMode = true)

if (paywallRepository.shouldShow(PAYWALL_HOME_ICON)) {
    showPaywall()
}

val data = paywallRepository.getPaywallData(PAYWALL_HOME_ICON)
val packages = paywallRepository.getPackages(data)

전체 화면 페이월 프래그먼트 (예시)

class PaywallFull01Fragment :
    BasePaywallFragment(),
    PackageSubCallback {

    override val bindingInflater = FragmentPaywallFull01Binding::inflate

    private val adapter by lazy { PackageSubAdapter(this) }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        binding.rcvPackage.apply {
            layoutManager = GridLayoutManager(context, 3)
            adapter = this@PaywallFull01Fragment.adapter
        }

        binding.btnContinue.setOnClickListener {
            adapter.getPaywallProduct()?.let { buy(it.product) }
        }

        binding.imgClose.setOnClickListener { close() }
        binding.txtPolicy.setOnClickListener { openPolicy() }
        binding.txtTerm.setOnClickListener { openTerm() }
    }

    override fun bindData(config: PaywallData, packages: List) {
        adapter.submitData(packages)
    }

    override fun onSelectPackage(paywallProduct: PaywallProduct) {
        binding.btnContinue.setText(
            PaywallCtaUtils.getCtaStringResId(paywallProduct)
        )

        val descRes = PaywallDescUtils.getDescResIds(
            paywallProduct,
            PaywallDescUtils.LayoutType.FULL_SCREEN
        )

        if (descRes.descRes != 0) {
            binding.txtDescription.text = PaywallDescUtils.formatDescription(
                requireContext(),
                descRes.descRes,
                paywallProduct
            )
        }
    }
}

단일‑패키지 페이월 다이얼로그 (예시)

class PaywallDialog01 :
    BasePaywallDialog() {

    override val bindingInflater = DialogPaywall01Binding::inflate
    private var currentItem: PaywallProduct? = null

    override fun bindData(config: PaywallData, packages: List) {
        val item = packages.firstOrNull() ?: return
        currentItem = item

        binding.txtPrice.text = item.product.priceText
        binding.btnContinue.setText(
            PaywallCtaUtils.getCtaStringResId(item)
        )

        val descRes = PaywallDescUtils.getDescResIds(
            item,
            PaywallDescUtils.LayoutType.DIALOG_1_ITEM
        )

        if (descRes.descRes != 0) {
            binding.txtDescription.text = PaywallDescUtils.formatDescription(
                requireContext(),
                descRes.descRes,
                item
            )
        }

        binding.btnContinue.setOnClickListener { currentItem?.let { buy(it) } }
        binding.imgClose.setOnClickListener { close() }
    }
}

사용 사례 – 온보딩, 하드 페이월, 기능 잠금, 유지, 세일‑오프, 이탈 방지.

CTA 로직

PaywallCtaUtils.getCtaStringResId(paywallProduct)

• CTA는 체험 / 세일 / 평생에 따라 달라집니다.
• packageIdOrigin != null이면 → 세일 모드가 활성화됩니다.
• 할인 %는 원래 가격을 기준으로 계산됩니다.
• 원래 가격은 취소선으로 표시됩니다.

구매 흐름 (SDK에서 처리):

1. 결제 요청
2. 검증
3. purchaseStatus 방출

Paywall A  → close
Sale Paywall Dialog → close
→ No further paywall

Quick Checklist

• 유효한 JSON 구성
• 배치 → 구성 매핑
• 저장소 초기화

Recommended UI Patterns

Subscription Flow Overview

• [ ] Test sandbox purchase
• [ ] Test sale / retention

Soft Paywall (user‑initiated purchase)

• Light upsell – does not interrupt the user experience.
• Allows management of the subscription after purchase.

Kotlin 구현

private val paywallRepository: PaywallRepository by inject()
private val launcher: PaywallLauncher by inject()

// Show the Subscribe CTA only when the paywall is enabled
ctlSub.isVisible =
    paywallRepository
        .getPaywallData(Constants.PaywallConfigKey.PAYWALL_SETTING)
        ?.enable == true

// Text description depends on purchase state
txtSubDes.text = if (paywallRepository.isPurchased()) {
    getString(R.string.unlocked_all_features)
} else {
    getString(R.string.upgrade_to_unlock_all)
}

// Show “Manage subscription” only for non‑lifetime purchases
ctlManageSubscription.isVisible =
    paywallRepository.isPurchased() &&
    paywallRepository.getCurrentPackagePurchased()?.type != PandaPackageType.LIFETIME

// 📌 Lifetime subscriptions do **not** need a “manage” button → matches Play Store UX
ctlSub.setOnClickListener {
    lifecycleScope.launch {
        val activity = activity ?: return@launch

        when (
            launcher.launch(
                activity,
                Constants.PaywallConfigKey.PAYWALL_SETTING
            )
        ) {
            PaywallResult.Success -> {
                // Update UI after a successful purchase
                ctlManageSubscription.isVisible =
                    paywallRepository.isPurchased() &&
                    paywallRepository.getCurrentPackagePurchased()?.type != PandaPackageType.LIFETIME

                txtSubDes.text = getString(R.string.unlocked_all_features)

                // Disable all ad formats
                NativeAdManager.disableAllAds()
                InterManager.disableAllAds()
                RewardAdsManager.disableAllAds()
                BannerAdManager.disableAllAds()
                PandaResumeAd.INSTANCE?.disableAllAds()
            }

            PaywallResult.Dismissed -> {
                // User closed the paywall
            }

            PaywallResult.NotShown -> {
                // Already purchased or not eligible to show the paywall
            }
        }
    }
}

UI 흐름 다이어그램

Setting Screen
   ↓
Subscribe CTA
   ↓ click
PaywallLauncher
   ↓
┌───────────────┬───────────────┬───────────────┐
│   Success     │   Dismissed   │   NotShown    │
│ Disable ads   │ Log event     │ Continue app  │
│ Update UI     │               │               │
└───────────────┴───────────────┴───────────────┘

체크리스트

• ✅ 소프트 페이월 – 강제 구매 없음.
• ✅ enable = false일 때 페이월이 숨겨짐.
• ✅ 평생 구독 ≠ “구독 관리”.
• ✅ 광고는 Success에서만 비활성화됨.
• ✅ UI가 즉시 업데이트 – 화면 새로고침 필요 없음.