Apps Kit SDK logoApps Kit SDK
개발자 문서 · AppsKitSDK (AKS) — Android 연동 가이드

6. 광고 형식별 호출

모든 광고 호출에는 플레이스홀더가 필요합니다. 플레이스홀더는 AKS 포털에서 광고 형식에 연결해 설정하는 문자열 키입니다(예: "1"). AKS는 런타임에 플레이스홀더를 기반으로 기본 광고 네트워크와 장애 시 사용할 대체 네트워크 목록을 결정합니다. 코드에서 광고 단위 ID를 직접 참조할 필요는 없습니다.

전면 광고

kotlin
// Load only
AdsManager.loadInterstitial(context, placeholder, object : AdsCallback() {
    override fun onLoaded() { }
    override fun onFailedToLoad() { }
    override fun onAdShown() { }
    override fun onAdDismissed() { }
    override fun onAdFailedToShow() { }
})

// Show a previously loaded interstitial
AdsManager.showInterstitial(activity, placeholder, callback)

// Load and show in one call
AdsManager.loadAndShowInterstitialAd(activity, placeholder, callback)

// Check availability before showing
AdsManager.isInterstitialAvailable(placeholder)

보상형 광고

kotlin
AdsManager.loadRewarded(context, placeholder, object : RewardedAdCallbacks() {
    override fun onRewardedLoaded() { }
    override fun onRewardedAdLoadFailure() { }
    override fun onRewardedCompleted() { }
    override fun onAdRewarded() { }
    override fun onAdRewardedAdDismissed() { }
    override fun onRewardedFailedToShow() { }
})

AdsManager.showRewarded(activity, placeholder, callbacks)

// Load and show in one call — simpler success/fail callback
AdsManager.loadAndShowRewardedAd(activity, placeholder, object : RewardedLoadAndShowCallback {
    override fun onRewardedAdSuccess() { }
    override fun onRewardedAdFailed() { }
})

AdsManager.isRewardedAvailable(placeholder)

앱 오프닝 광고

kotlin
AdsManager.loadAppOpen(application, placeholder, object : AppOpenAdCallbacks() {
    override fun onLoaded() { }
    override fun onFailedToLoad() { }
    override fun onDismiss() { }
    override fun onAdShown() { }
    override fun onAdFailToShow() { }
})

AdsManager.showAppOpen(activity, placeholder, callbacks)

앱 오프닝 광고를 직접 관리하는 대신 AKS의 자체 스플래시/앱 오프닝 처리(isAppOpenAtApplicationLvl 원격 구성 플래그로 제어)를 사용하려면, AppsKitSDKApplication 서브클래스에서 loadDefaultAppOpen / showDefaultAppOpen을 사용하세요. 또는 기본 Application 클래스에 전체 처리 과정이 이미 구현된 requestSplashAppOpenAd(callbacks, addInDefaultDelay)를 호출하기만 하면 됩니다.

배너 광고

kotlin
AdsManager.loadBanner(context, placeholder, object : BannerCallback() {
    override fun onBannerLoaded() { }
    override fun onBannerFailedToLoad() { }
    override fun onBannerClicked() { }
    override fun onBannerShown() { }
    override fun onBannerSizeChanged(bannerSizes: BannerSizes) { }
    override fun setBannerSize(width: Double, height: Double) { }
})

// layout is a FrameLayout (BannerContainer) you've placed in your screen
AdsManager.showBanner(activity, layout, placeholder, callback)

BannerSizes: BANNER (320×50), LARGE_BANNER (320×100), MEDIUM_RECTANGLE (300×250), FULL_BANNER (468×60).

네이티브 광고

kotlin
AdsManager.loadNative(activity, placeholder, isShowInScrollView = false, object : NativeCallback() {
    override fun onNativeLoaded() { }
    override fun onNativeFailedToLoad() { }
    override fun onNativeClicked() { }
    override fun onNativeShown() { }
})

// frameLayout is the BannerContainer that will host the native ad view; res is an
// optional custom native-ad layout resource (pass null to use AKS's default layout)
AdsManager.showNative(activity, frameLayout, placeholder, isShowInScrollView = false, res = null, callback)

// Show the native ad using the design you created for this placeholder in the
// AKS portal, instead of a layout resource — see below.
AdsManager.showTemplatedNative(activity, frameLayout, placeholder, isShowInScrollView = false, callback)

showTemplatedNative는 앱 코드가 아닌 AKS 포털에서 네이티브 광고의 디자인을 만들고 할당한 플레이스홀더에 사용합니다. 앱에서 레이아웃을 제공하는 방식이 아니므로 res 매개변수 자체가 없습니다. AKS는 해당 플레이스홀더에 적용할 포털 템플릿을 확인하고 가져온 뒤(최초로 가져온 후 캐시됨), showNative와 동일한 로드/표시 파이프라인을 통해 해당 템플릿으로 네이티브 광고를 렌더링합니다. 플레이스홀더에 할당된 템플릿이 없거나 템플릿을 가져올 수 없는 경우에도 광고를 실패 처리하지 않고 자체 내장 기본 네이티브 디자인을 사용합니다. 따라서 포털에 템플릿을 설정하기 전에도 안전하게 호출할 수 있습니다.

기능 프로모션

기능 프로모션은 아직 특정 기능을 잠금 해제하지 않은 사용자에게 해당 앱 기능을 교차 홍보하는 AKS의 자체 광고 형식입니다. AKS 네트워크만 사용하며 AdMob/MAX 등의 네트워크는 사용하지 않습니다. 홍보할 항목은 AKS 포털의 서버 측 설정에서 플레이스홀더별로 구성합니다.

kotlin
// Optional — exclude features the user already has unlocked from being promoted
AdsManager.setFeaturesAvailable(listOf("premium_theme", "no_ads"))

AdsManager.showFeaturePromotion(activity, placeholder, object : OnFeaturePromotionClicked {
    override fun onFeaturePromotionClicked(targetScreen: String) {
        // user tapped the promotion — navigate them to targetScreen
    }

    override fun onFailToShowFeaturePromotion(errorMessage: String) { }
})

페이월

페이월은 기능 프로모션과 마찬가지로 AKS가 자체 호스팅하는 또 다른 형식입니다. 페이월의 디자인, 문구, 가격 표시 레이아웃, 요금제는 모두 AKS 포털에서 PAYWALLS 광고 형식에 대한 서버 측 설정으로 구성합니다. AKS는 화면을 렌더링하고 가격 표시, 요금제 선택, 실제 Google Play / Amazon 구매, 결과 전달까지 전체 구매 흐름을 직접 처리합니다. 결제 API를 직접 호출하거나 페이월을 표시하기 위해 자체 화면으로 이동할 필요가 없습니다. AKS가 전달받은 activity 위에 오버레이로 표시합니다.

kotlin
// Preload — call ahead of time (e.g. in onCreate) so the paywall is ready to show instantly
// later. Resolves against "{placeholder}_LOAD" in the AKS portal config, NOT the bare
// placeholder — see the note below.
PaywallManager.loadPaywall(placeholder, object : PaywallCallback() {
    override fun onLoaded(paywallId: String) { }
    override fun onFailedToLoad(reason: String) { }
    override fun onReadyToShow(paywallId: String) { }   // not used on this path
    override fun onFailedToShow(reason: String) { }     // not used on this path
}, languageCode)

// Show — presents the paywall on `activity`. If it wasn't already loaded, this loads it
// first and shows it as soon as it's ready, same combined load-then-show convenience as
// loadAndShowInterstitialAd. Resolves against the BARE placeholder (no "_LOAD" suffix).
PaywallManager.showPaywall(PlatformActivity(activity), placeholder, object : PaywallCallback() {
    override fun onLoaded(paywallId: String) { }
    override fun onFailedToLoad(reason: String) { }
    override fun onReadyToShow(paywallId: String) { }     // paywall is now on screen
    override fun onFailedToShow(reason: String) { }       // not eligible, or failed to load

    override fun onPurchaseCompleted(result: PaywallPurchaseResult) {
        // result.sku, result.product (matched from the paywall's own catalog, nullable),
        // result.purchaseToken, result.purchaseTimeUtc — grant whatever entitlement this sku
        // unlocks, e.g.:
        AppsKitSDK.setRemoveAdsStatus(true)
    }
    override fun onPurchaseFailed(message: String) { }
    override fun onDismissed() { }
    override fun onRestoreCompleted(results: List<PaywallPurchaseResult>) {
        // fired if the user tapped the presented paywall's own "Restore" action
    }
}, languageCode)

loadPaywall과 showPaywall은 동일한 placeholder 문자열에 대해 서로 다른 포털 게재 위치 항목을 조회합니다. loadPaywall은 "{placeholder}_LOAD"를 조회합니다. 이는 전면 광고 형식이 내부적으로 사용하는 _LOAD 접미사 기반 사전 로드 규칙과 같습니다. 반면 showPaywall과 이 메서드의 표시 자격 확인 로직은 접미사 없는 placeholder를 조회합니다. 사전 로드는 선택 사항이며, 미리 로드된 항목이 없으면 showPaywall이 필요할 때 로드합니다. 다만 사전 로드를 사용하는 경우 두 항목이 서로 다른 페이월 디자인을 가리킬 수 있으므로 AKS 포털에서 두 항목을 모두 설정하세요.

PaywallCallback에서 abstract로 선언된 메서드는 onLoaded/onFailedToLoad/onReadyToShow/onFailedToShow뿐입니다. onPurchaseCompleted/onPurchaseFailed/onDismissed/onRestoreCompleted는 아무 작업도 하지 않는 기본 구현이 있는 open 메서드이므로, 로드만 수행하는 호출부에서는 재정의할 필요가 없습니다.

languageCode는 선택 사항입니다. 지정하면 백엔드로 전달되어 페이월의 디자인과 문구를 현지화하는 데 사용됩니다.

구매 복원

현재 페이월 표시 여부와 관계없이 앱의 자체 "구매 복원" 항목이나 버튼에서 사용할 수 있는 독립적인 진입점입니다.

kotlin
PaywallManager.restorePurchases(
    PlatformContext(context),
    PlatformActivity(activity),
    null, // storeType — null resolves to whatever AppsKitSDKApplication.setPlatform() declared
    object : PaywallResultCallback {
        override fun onPurchaseCompleted(result: PaywallPurchaseResult) { }   // not invoked on this path
        override fun onPurchaseFailed(message: String) { }                    // not invoked on this path
        override fun onRestoreCompleted(results: List<PaywallPurchaseResult>) {
            // empty list = nothing to restore; otherwise sync your entitlement from each sku
        }
    }
)

restorePurchases는 onRestoreCompleted만 호출합니다. PaywallResultCallback에 다른 두 멤버가 있는 이유는 동일한 인터페이스가 표시 중인 페이월 화면의 구매 결과 전달에도 내부적으로 사용되기 때문입니다. 해당 결과는 위의 showPaywall에 있는 onPurchaseCompleted/onPurchaseFailed를 통해 실제로 전달됩니다.

결과에 따른 이용 권한 처리

onPurchaseCompleted와 onRestoreCompleted는 그 자체로 앱의 상태를 변경하지 않습니다. AKS는 발생한 결과를 전달하고, 어떤 기능을 잠금 해제할지는 앱에서 결정합니다.

kotlin
private fun syncEntitlementFrom(results: List<PaywallPurchaseResult>) {
    val hasRemoveAds = results.any { it.sku in YOUR_REMOVE_ADS_SKUS }
    AppsKitSDK.setRemoveAdsStatus(hasRemoveAds)
    // drive your own subscription/Pro flag the same way, from YOUR_SUBSCRIPTION_SKUS
}

복원 시에는 AKS를 기준 정보로 삼으세요. results에 없는 SKU는 사용자가 현재 보유하고 있지 않다는 뜻입니다. 따라서 결과에 있는 항목의 이용 권한을 부여하는 것뿐 아니라, 없는 항목에 해당하는 이용 권한도 해제해야 합니다. 그렇지 않으면 구독이 만료된 사용자가 복원을 수행했을 때 이용 권한이 영구적으로 유지됩니다. 반면 단일 구매 완료 결과는 그 자체로 해당 이용 권한을 획득했다는 확정적인 사실입니다. 해당 권한을 부여하되 다른 이용 권한의 상태는 변경하지 마세요.