KeyPuff

外观

Android 接入指南 ​

本指南说明 Android App（Java）如何接入 KeyPuff SDK：安装依赖、初始化，以及各广告格式的接入代码。示例 API 与类名均取自 SDK 源码与 demo 工程。

环境要求 ​

  • minSdkVersion 21（demo 工程以 compileSdkVersion 31 编译）；
  • App 需有网络权限 android.permission.INTERNET。

隐私与初始化时机 ​

必须在用户同意 App 隐私政策之后再调用 SDK 初始化（demo 工程以隐私弹窗演示了该流程）。可通过 AdvanceSDK.setPrivacyController(AdvancePrivacyController) 控制位置、OAID、Android ID、应用列表等采集开关，未取得授权的项返回 false / 空值。详见 SDK 合规接入指引。

安装（Gradle） ​

核心 SDK 由 KeyPuff 自建制品仓库（repo.creative.zadervice.com）分发：工程根 build.gradle 声明仓库后按坐标引入。

groovy
// 工程根 build.gradle
allprojects {
    repositories {
        google()
        mavenCentral()
        // KeyPuff 制品仓库（http 内网地址需 allowInsecureProtocol = true）
        maven { url 'https://repo.creative.zadervice.com/maven' }
    }
}
groovy
dependencies {
    // KeyPuff 核心 SDK（必须，补丁版：服务基址与密钥已在出包时写入）
    implementation "cn.keybuff.keypuff:advancecore:5.2.7.0-kp1"
    // Mercury 基础库（必须）：核心 SDK 依赖其中的 com.bayes.sdk.basic，不使用倍业 Mercury 渠道也要引入
    implementation "io.github.bayescom:mercury-sdk:4.7.2"
    // 渠道 adapter（按需，示例）：
    // implementation "com.github.bayescom.Android_AdvanceSDK:advancemry:<version>"    // 倍业 Mercury
    // implementation "com.github.bayescom.Android_AdvanceSDK:advancesigmob:<version>" // Sigmob
    // …
}

Mercury 基础库仍引用 android.support，工程的 gradle.properties 需开启 Jetifier，否则 App 启动即崩溃（BYFileProvider）：

properties
android.useAndroidX=true
android.enableJetifier=true

确切的依赖行与版本号以控制台「SDK 中心」按您的应用生成的列表为准（该列表已排除 App 自接的渠道），复制后同步工程即可。

说明：cn.keybuff.keypuff:advancecore 是 KeyPuff 私有化补丁版（私服坐标）；上游原始坐标（com.github.bayescom.Android_AdvanceSDK:advancecore:<version>，JitPack）仅用于直连上游、未接入 KeyPuff 服务时参考，渠道 adapter 仍从上游仓库拉取。

初始化 ​

在 Application.onCreate 中用 appid（应用 id） 初始化，appid 在控制台「应用与广告位」查看：

java
import com.advance.AdvanceSDK;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // 三个参数依次为：context 上下文、appId 媒体 id、isDebug 调试开关
        AdvanceSDK.initSDK(this, "100001", false);   // 替换为控制台分配的应用 id（appid）
        // 可选：隐私项控制 AdvanceSDK.setPrivacyController(new AdvancePrivacyController(){…})
    }
}

使用自定义渠道时

Android SDK 在首次安装后的第一次启动中无法加载自定义渠道（渠道 ID 90001 起），需要在 initSDK 之前先拉取自定义渠道配置，做法见 Adapter 集成 · 自定义渠道。只使用内置渠道的 App 不受影响。

开屏 ​

java
import com.advance.AdvanceSplash;
import com.advance.AdvanceSplashListener;

advanceSplash = new AdvanceSplash(this, "10000001", adContainer, null /* 跳过按钮视图，可空 */); // 替换为您的 adspotid
advanceSplash.setAdListener(new AdvanceSplashListener() {
    @Override public void onAdLoaded() {
        advanceSplash.show();          // 加载成功后展示
    }
    @Override public void jumpToMain() { /* 开屏结束，跳转主页 */ }
    @Override public void onAdShow() {}
    @Override public void onAdFailed(AdvanceError e) { /* e.code / e.msg */ }
    @Override public void onAdClicked() {}
    @Override public void onSdkSelected(String id) { /* 胜出渠道 */ }
});
advanceSplash.loadOnly();              // 加载（也可 loadStrategy() 加载并展示）

横幅 ​

java
import com.advance.AdvanceBanner;
import com.advance.AdvanceBannerListener;

advanceBanner = new AdvanceBanner(this, adContainer, "10000002");
advanceBanner.setAdListener(new AdvanceBannerListener() {
    @Override public void onAdLoaded() {
        advanceBanner.show();          // 展示到 adContainer
    }
    @Override public void onDislike() { adContainer.removeAllViews(); }
    @Override public void onAdShow() {}
    @Override public void onAdFailed(AdvanceError e) {}
    @Override public void onAdClicked() {}
    @Override public void onSdkSelected(String id) {}
});
advanceBanner.loadOnly();

插屏 ​

java
import com.advance.AdvanceInterstitial;
import com.advance.AdvanceInterstitialListener;

AdvanceInterstitial ad = new AdvanceInterstitial(activity, "10000003");
ad.setAdListener(new AdvanceInterstitialListener() {
    @Override public void onAdReady() {
        ad.show();                     // 广告就绪后展示
    }
    @Override public void onAdClose() {}
    @Override public void onAdShow() {}
    @Override public void onAdFailed(AdvanceError e) {}
    @Override public void onAdClicked() {}
    @Override public void onSdkSelected(String id) {}
});
ad.loadStrategy();

激励视频 ​

激励视频支持服务端回调验签，如需服务端发奖请先在控制台配置激励回调：

java
import com.advance.AdvanceRewardVideo;
import com.advance.AdvanceRewardVideoListener;
import com.advance.RewardServerCallBackInf;

AdvanceRewardVideo ad = new AdvanceRewardVideo("10000004");
// 服务端验证需要（配合控制台「激励回调」配置）
ad.setUserId("用户唯一标识");            // 服务端验证必须
ad.setRewardName("金币");               // 激励名称，可选
ad.setRewardCount(1);                  // 激励数量，可选
ad.setExtraInfo("透传参数");            // 可选
ad.setAdListener(new AdvanceRewardVideoListener() {
    @Override public void onAdLoaded() {
        if (ad.isValid()) ad.show(activity);
    }
    @Override public void onAdReward() { /* 客户端激励发放 */ }
    @Override public void onRewardServerInf(RewardServerCallBackInf inf) { /* 服务端验证信息 */ }
    @Override public void onVideoComplete() {}
    @Override public void onVideoCached() {}
    @Override public void onAdClose() {}
    @Override public void onAdShow() {}
    @Override public void onAdFailed(AdvanceError e) {}
    @Override public void onAdClicked() {}
    @Override public void onSdkSelected(String id) {}
});
ad.loadStrategy();

信息流（模板渲染） ​

java
import com.advance.AdvanceNativeExpress;
import com.advance.AdvanceNativeExpressListener;

AdvanceNativeExpress ad = new AdvanceNativeExpress(activity, "10000005");
ad.setAdContainer(adContainer);                 // 必须：广告父布局
ad.setExpressViewAcceptedSize(360, 0);          // 可选：模板尺寸（dp），高度 0 自适应
ad.setAdListener(new AdvanceNativeExpressListener() {
    @Override public void onAdLoaded() {
        ad.show();                              // 渲染到 adContainer
    }
    @Override public void onAdRenderSuccess(View view) {}
    @Override public void onAdShow(View view) {}
    @Override public void onAdClose(View view) {}
    @Override public void onAdRenderFailed(View view) {}
    @Override public void onAdFailed(AdvanceError e) {}
    @Override public void onAdClicked(View view) {}
    @Override public void onSdkSelected(String id) {}
});
ad.loadStrategy();

信息流（自渲染） ​

自渲染需要先绑定自绘视图（根布局、视频、Logo、点击视图），再调用 show()：

java
import com.advance.AdvanceRenderFeed;
import com.advance.core.srender.*;

AdvanceRenderFeed ad = new AdvanceRenderFeed(this, "10000006");
ad.setLoadListener(new AdvanceRFLoadListener() {
    @Override public void onADLoaded(AdvanceRFADData adData) {
        bindAd(adData);                        // 绑定自渲染视图后展示
    }
    @Override public void onAdFailed(AdvanceError e) {}
});
ad.loadStrategy();

private void bindAd(AdvanceRFADData adData) {
    // 用自有布局取 adData 素材（标题 / 描述 / 图标等）完成渲染
    AdvanceRFMaterialProvider provider = new AdvanceRFMaterialProvider();
    provider.rootView = advRFRootView;         // 必须：广告根布局（AdvRFRootView）
    provider.videoView = advRFVideoView;       // 必须：视频视图（AdvRFVideoView）
    provider.logoView = advRFLogoView;         // 必须：Logo 视图（AdvRFLogoView）
    provider.clickViews.add(mCreativeButton);  // 必须：响应点击的 view
    ad.setRfMaterialProvider(provider);        // 必须：在 show 之前调用
    ad.setRenderEventListener(new AdvanceRFEventListener() {
        @Override public void onAdShow(AdvanceRFADData adData) {}
        @Override public void onAdClicked(AdvanceRFADData adData) {}
        @Override public void onAdClose(AdvanceRFADData adData) {}
        @Override public void onAdErr(AdvanceRFADData adData, AdvanceError e) {}
    });
    ad.show();                                 // 必须：绑定之后调用
}

全屏视频 ​

java
import com.advance.AdvanceFullScreenVideo;
import com.advance.AdvanceFullScreenVideoListener;

AdvanceFullScreenVideo ad = new AdvanceFullScreenVideo(activity, "10000007");
ad.setAdListener(new AdvanceFullScreenVideoListener() {
    @Override public void onAdLoaded() {
        ad.show();
    }
    @Override public void onVideoComplete() {}
    @Override public void onVideoSkipped() {}
    @Override public void onVideoCached() {}
    @Override public void onAdClose() {}
    @Override public void onAdShow() {}
    @Override public void onAdFailed(AdvanceError e) {}
    @Override public void onAdClicked() {}
    @Override public void onSdkSelected(String id) {}
});
ad.loadStrategy();

Draw 视频 ​

java
import com.advance.AdvanceDraw;
import com.advance.AdvanceDrawListener;

AdvanceDraw ad = new AdvanceDraw(activity, "10000008");
ad.setAdContainer(adContainer);          // 必须：广告承载布局
ad.setAdListener(new AdvanceDrawListener() {
    @Override public void onAdLoaded() {
        ad.show();
    }
    @Override public void onAdShow() {}
    @Override public void onAdClicked() {}
    @Override public void onAdFailed(AdvanceError e) {}
    @Override public void onSdkSelected(String id) {}
});
ad.loadStrategy();

下一步 ​

  • 集成各渠道 adapter：Adapter 集成
  • 激励视频服务端验签：激励视频服务端回调
  • 策略缓存（S9）：loadStrategy() 的结果由服务端按广告位级配置缓存与下发——响应 setting.use_cache=1 时 SDK 在 cache_dur 秒内复用策略（不配置用默认 3 天），降低请求量；开关与时长在 KeyPuff 后台按广告位配置。
  • 遇到问题：常见问题

App 广告聚合与变现平台

Copyright © 2026 KeyPuff 运营方（主体名称待业务确认）