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