Apps Kit SDK logoApps Kit SDK
文档 · AppsKitSDK (AKS) — Android 集成指南

5. 初始化 SDK 和 AdsManager

5.1 Application 类

继承 AppsKitSDKApplication 并实现其五个抽象成员:

kotlin
class YourApplication : AppsKitSDKApplication() {

    // Encrypted default-config JSON to fall back on before Remote Config is fetched.
    // Provided to you from the AKS portal for your app.
    override fun setAKSDefaultConfigs(): String = "<encrypted-config-json-from-aks-portal>"

    override fun isTestMode(): Boolean = BuildConfig.DEBUG

    override fun isDevMode(): Boolean = BuildConfig.DEBUG

    override fun setPlatform(): Platform = Platform.GOOGLE // or Platform.AMAZON

    override fun onConfigsReadyToUse(remoteConfig: FirebaseRemoteConfig) {
        // Called once Firebase Remote Config has been fetched/activated.
        // Optional hook if you need to read custom remote-config keys yourself.
    }
}

基类的 onCreate() 已经为你完成了主要工作:调用 AppsKitSDK.initialize/setPlatform/setTestMode/setDevMode,获取并保存默认配置,启动 manageRemoteConfigs(),并调用 AppsKitSDK.initMMP() 来接入 AppsFlyer/Adjust/Solar Engine。你无需自行调用这些方法。

5.2 不继承 AppsKitSDKApplication 的初始化方式

并非必须继承 AppsKitSDKApplication,它只是一个便捷封装。如果你的应用已有自己的 Application 基类且无法替换,可以直接在自己的 Application.onCreate() 中调用它内部使用的同一组 AppsKitSDK 方法:

kotlin
class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        FirebaseApp.initializeApp(this)

        AppsKitSDK.initialize(PlatformContext(this), this)
        AppsKitSDK.setPlatform(Platform.GOOGLE) // or Platform.AMAZON
        AppsKitSDK.setTestMode(BuildConfig.DEBUG)
        AppsKitSDK.setDevMode(BuildConfig.DEBUG)
        AppsKitSDK.setTimeToFetchRemoteConfigInSeconds(3600) // optional, defaults to 3600

        AppsKitSDK.saveDefaultConfigJson("<encrypted-config-json-from-aks-portal>")
        AppsKitSDK.manageRemoteConfigs(object : OnRemoteConfigAvailable {
            override fun onRemoteConfigReadyToFetch(remoteConfig: FirebaseRemoteConfig) {
                // optional — your own hook into the fetched remote config
            }
        })

        AppsKitSDK.initMMP() // wires up AppsFlyer / Adjust / Solar Engine from remote-config keys

        // AppsKitSDKApplication does this for you via ActivityLifecycleCallbacks. Without it,
        // AppsKitSDK has no "current activity" — native-ad preloading and any code that calls
        // AppsKitSDK.getCurrentActivity() won't have a target to work with.
        registerActivityLifecycleCallbacks(object : Application.ActivityLifecycleCallbacks {
            override fun onActivityResumed(activity: Activity) {
                AppsKitSDK.setCurrentActivity(PlatformActivity(activity))
                Adjust.onResume() // keeps Adjust session tracking accurate
            }
            override fun onActivityPaused(activity: Activity) {
                Adjust.onPause()
            }
            override fun onActivityCreated(activity: Activity, bundle: Bundle?) {}
            override fun onActivityStarted(activity: Activity) {}
            override fun onActivityStopped(activity: Activity) {}
            override fun onActivitySaveInstanceState(activity: Activity, bundle: Bundle) {}
            override fun onActivityDestroyed(activity: Activity) {}
        })
    }
}

不继承该基类,就无法直接使用网络连接广播/对话框处理,以及内置的“应用级开屏广告”流程(requestSplashAppOpenAd/showAppOpenAd,由 onStart 自动触发)。这些都是 AppsKitSDKApplication 自身的实例方法,并未在 AppsKitSDK 对象上公开。如果仍希望在冷启动时展示开屏广告,请在自己的启动流程中需要展示广告的位置,自行调用 AdsManager.loadAppOpen/AdsManager.showAppOpen(参见 §6)。

5.3 Activity

继承 AppsKitSDKBaseActivity(适用于基于 AppCompatActivity 的页面)或 AppsKitSDKBaseComponentActivity(适用于普通 ComponentActivity 页面或纯 Compose 页面):

kotlin
class HomeActivity : AppsKitSDKBaseActivity() {

    override fun setScreenNameAndId(): Pair<Int, String> = Pair(1, "Home")

    override fun enableAppAutoUpdate(): Boolean = true

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState) // required — this drives ad-network init, preloading,
                                            // session/day tracking, and the auto SCREEN event
        setContent { /* your Compose UI */ }
    }
}

继承这些基类后,你将自动获得以下功能:首个页面的广告网络初始化和预加载、在 onResume/onPause 中转发 IronSource 生命周期回调、会话/天数统计、网络连接对话框、可选的应用内更新提示,以及用于触发当前页面相关事件的 sendAKSEvent(...)(参见 §7)。(Adjust 自身的 onResume/onPause 回调转发在 Application 层处理,而非此处,参见 §5.2。)

网络连接对话框

这两个 Activity 基类都会在 onResume() 中监听网络连接状态。默认情况下,连接断开时会显示阻止用户继续操作的“无网络连接”对话框,并在重新连接后自动关闭。除非手动关闭,否则每个页面都会启用此功能:

kotlin
class HomeActivity : AppsKitSDKBaseActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        showInternetConnectivity(false) // opt this screen out of the automatic dialog
    }

    // Called on every connectivity change, dialog or not — hook your own UI here
    override fun onInternetConnectivityChange(isInternetAvailable: Boolean?) {
        // e.g. show/hide your own offline banner
    }

    // Optional — return an anchor view to get a "back online" Snackbar when the
    // dialog dismisses on reconnect. Returns null (no Snackbar) by default.
    override fun getSnackBarView(): View? = findViewById(R.id.rootLayout)
}

调用 showInternetConnectivity(false) 后,AKS 仍会调用 onInternetConnectivityChange,但无论实际连接状态如何,传入的值始终为 true。关闭此管理功能后,它便不再跟踪真实的网络连接状态。如果需要准确的状态来更新自定义离线界面,请自行检测网络连接。

仅限竖屏

要将页面锁定为竖屏,请调用 restrictPortraitOnly()(受保护方法,两个 Activity 基类均提供):

kotlin
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    restrictPortraitOnly()
}

此方法会代你调用 setRequestedOrientation(SCREEN_ORIENTATION_PORTRAIT),但在 Android 8.0(API 26)上会特意跳过,因为在该系统版本中,对使用半透明/悬浮主题的 Activity 调用 setRequestedOrientation 存在已知的崩溃问题。

5.4 用户同意与广告初始化

获得用户同意后(例如通过 Google 的 UMP/CMP 流程),请告知 AKS,以便其允许展示广告:

kotlin
AdsManager.initializeAds(userHasGivenConsent = true, isCCPAConsent = true)

5.5 移除广告 / 应用内购买(IAP)控制

如果你的应用提供付费“移除广告”功能,请通过 AKS 接入,而不是自行控制广告调用。每次加载/展示调用都会在内部检查此标志:

kotlin
AppsKitSDK.setRemoveAdsStatus(true)   // call after a successful purchase/restore
AppsKitSDK.getRemoveAdsStatus()       // check current status