@24jieqi/react-native-brayant-ad 0.1.24 → 0.1.26

package/README.md

@@ -98,9 +98,47 @@ EmuAnim = 'default' | 'none' | 'catalyst' | 'slide' | 'fade';
 | codeid | 广告位id     | string  | -       | 是       |
 | anim   | 广告进入方式 | EmuAnim | default | 否       |
 
+### preloadSplashAd (Android 推荐)
+
+**Android 端推荐使用预加载方式，可避免启动页结束后出现白屏。**
+
+在应用启动时（init 之后）预加载开屏广告，展示时直接使用已加载的广告。
+
+```ts
+// 预加载开屏广告
+await preloadSplashAd({ codeid: 'your_code_id' });
+
+// 展示广告（使用预加载的广告，无白屏）
+const splashAd = dyLoadSplashAd({ codeid: 'your_code_id' });
+```
+
+| 参数   | 说明     | 类型   | 默认值 | 是否必填 |
+| ------ | -------- | ------ | ------ | -------- |
+| codeid | 广告位id | string | -      | 是       |
+
+### hasPreloadedSplashAd
+
+检查是否有预加载的广告可用（Android）。
+
+```ts
+const { hasAd, status } = await hasPreloadedSplashAd();
+// hasAd: boolean - 是否有可用的预加载广告
+// status: number - 预加载状态 (0:未加载 1:加载中 2:成功 3:失败)
+```
+
+### clearPreloadedSplashAd
+
+清除预加载的广告缓存（Android）。
+
+```ts
+clearPreloadedSplashAd();
+```
+
 ## 如何使用
 
-> 这边案列默认全部init初始化后
+### 基础用法（实时加载）
+
+> 注意：这种方式在 Android 端可能会出现白屏
 
 ```tsx
 import { dyLoadSplashAd } from '@24jieqi/react-native-brayant-ad';
@@ -142,6 +180,123 @@ const ScrenPage = () => {
 };
 ```
 
+### 推荐用法（预加载 - Android）
+
+**Android 端推荐使用预加载方式，避免启动页到广告之间出现白屏。**
+
+```tsx
+import {
+  init,
+  preloadSplashAd,
+  hasPreloadedSplashAd,
+  dyLoadSplashAd,
+} from '@24jieqi/react-native-brayant-ad';
+import { useEffect } from 'react';
+
+const App = () => {
+  useEffect(() => {
+    const initialize = async () => {
+      // 1. 初始化 SDK
+      await init({
+        appid: 'your_app_id',
+        app: '应用名称',
+        debug: false,
+      });
+
+      // 2. Android: 预加载开屏广告（避免白屏）
+      if (Platform.OS === 'android') {
+        await preloadSplashAd({ codeid: 'your_splash_code_id' });
+        console.log('开屏广告预加载完成');
+      }
+    };
+
+    initialize();
+  }, []);
+
+  // 3. 展示开屏广告（Android使用预加载，iOS实时加载）
+  const showSplash = async () => {
+    // 检查预加载状态（可选）
+    if (Platform.OS === 'android') {
+      const { hasAd } = await hasPreloadedSplashAd();
+      console.log('是否有预加载广告:', hasAd);
+    }
+
+    const splashAd = dyLoadSplashAd({
+      codeid: 'your_splash_code_id',
+      anim: 'default',
+    });
+
+    splashAd.subscribe('onAdShow', (event) => {
+      console.log('广告展示', event);
+    });
+
+    splashAd.subscribe('onAdClose', (event) => {
+      console.log('广告关闭', event);
+    });
+
+    splashAd.subscribe('onAdError', (error) => {
+      console.log('广告错误', error);
+    });
+  };
+
+  return (
+    // ...
+  );
+};
+```
+
+### 在应用启动时自动展示开屏广告
+
+```tsx
+import { init, preloadSplashAd, dyLoadSplashAd } from '@24jieqi/react-native-brayant-ad';
+import { hide } from 'react-native-bootsplash';
+
+const SplashAdManager = () => {
+  useEffect(() => {
+    const showSplashAdOnLaunch = async () => {
+      try {
+        // 1. 初始化广告 SDK
+        await init({ appid: 'your_app_id', app: '应用名称' });
+
+        // 2. Android: 预加载广告
+        if (Platform.OS === 'android') {
+          await preloadSplashAd({ codeid: 'your_splash_code_id' });
+        }
+
+        // 3. 展示广告（Android使用预加载，无白屏）
+        const splashAd = dyLoadSplashAd({
+          codeid: 'your_splash_code_id',
+          anim: 'fade',
+        });
+
+        splashAd.subscribe('onAdShow', () => {
+          console.log('广告展示');
+          // Android: 此时可以隐藏启动页（广告已准备好）
+          hide({ fade: true });
+        });
+
+        splashAd.subscribe('onAdClose', () => {
+          console.log('广告关闭');
+        });
+
+        splashAd.subscribe('onAdError', (error) => {
+          console.log('广告加载失败', error);
+          // 出错时也要隐藏启动页
+          hide({ fade: true });
+        });
+      } catch (error) {
+        console.error('广告初始化失败:', error);
+        hide({ fade: true });
+      }
+    };
+
+    showSplashAdOnLaunch();
+  }, []);
+
+  return null;
+};
+```
+
 # 2. 激励视频
 
 ## API
@@ -348,6 +503,52 @@ const RewardVideoPage = () => {
 
 # 5. Banner广告
 
+> 注意：Banner广告目前仅支持Android平台
+
+## API
+
+### preloadBannerAd
+
+预加载 Banner 广告（Android 专用）
+
+在组件渲染前调用，提前加载广告数据，减少白屏时间。预加载的广告会缓存 5 分钟，过期后自动失效。
+
+| 参数     | 说明         | 类型   | 默认值 | 是否必填 |
+| -------- | ------------ | ------ | ------ | -------- |
+| codeid   | 广告位 ID    | string | -      | 是       |
+| adWidth  | 广告宽度(dp) | number | 320    | 否       |
+| adHeight | 广告高度(dp) | number | 50     | 否       |
+
+```tsx
+import { NativeModules } from 'react-native';
+const { BannerAdModule } = NativeModules;
+
+// 在页面进入前预加载
+useEffect(() => {
+  BannerAdModule.preloadBannerAd({
+    codeid: 'your_codeid',
+    adWidth: 320,
+    adHeight: 50,
+  });
+}, []);
+```
+
+### hasPreloadedBannerAd
+
+检查是否有预加载的 Banner 广告
+
+```tsx
+const hasCache = await BannerAdModule.hasPreloadedBannerAd('your_codeid');
+```
+
+### clearPreloadedBannerAd
+
+清除预加载的 Banner 广告缓存
+
+```tsx
+BannerAdModule.clearPreloadedBannerAd();
+```
+
 ## 组件
 
 ### BannerAdView
@@ -366,10 +567,10 @@ const RewardVideoPage = () => {
 | onAdShow          | 广告展示事件       | Function  | -      | 否       |
 | onAdDislike       | 用户不感兴趣事件   | Function  | -      | 否       |
 
-> 注意：Banner广告目前仅支持Android平台
-
 ## 使用
 
+### 基础用法
+
 ```tsx
 import { BannerAdView, init } from '@24jieqi/react-native-brayant-ad';
 import { useEffect, useState } from 'react';
@@ -418,8 +619,87 @@ const BannerAdPage = () => {
 };
 ```
 
+### 推荐用法（预加载）
+
+```tsx
+import { BannerAdView } from '@24jieqi/react-native-brayant-ad';
+import { NativeModules } from 'react-native';
+import { useEffect, useState } from 'react';
+import { View } from 'react-native';
+
+const { BannerAdModule } = NativeModules;
+
+const BannerAdPage = () => {
+  const [showBannerView, setShowBannerView] = useState(false);
+
+  useEffect(() => {
+    // 先预加载广告，再显示组件
+    const preloadAndShow = async () => {
+      try {
+        await BannerAdModule.preloadBannerAd({
+          codeid: 'your_codeid',
+          adWidth: 320,
+          adHeight: 50,
+        });
+      } catch (error) {
+        console.log('预加载失败', error);
+      } finally {
+        // 无论预加载成功与否，都显示组件
+        setShowBannerView(true);
+      }
+    };
+
+    preloadAndShow();
+  }, []);
+
+  return (
+    <View>
+      <BannerAdView
+        codeid={'your_codeid'}
+        adWidth={320}
+        adHeight={50}
+        visible={showBannerView}
+        onAdRenderSuccess={(data: any) => {
+          console.log('Banner 广告渲染成功！', data);
+        }}
+        onAdError={(err: any) => {
+          console.log('Banner 广告加载失败！', err);
+        }}
+      />
+    </View>
+  );
+};
+```
+
 # 6. 信息流广告
 
+## API
+
+### preloadFeedAd
+
+预加载信息流广告（Android 专用）
+
+在组件渲染前调用，提前加载广告数据，减少白屏时间。
+
+| 参数    | 说明         | 类型   | 默认值 | 是否必填 |
+| ------- | ------------ | ------ | ------ | -------- |
+| appid   | 应用 ID      | string | -      | 是       |
+| codeid  | 广告位 ID    | string | -      | 是       |
+| adWidth | 广告宽度(dp) | string | '280'  | 否       |
+
+```tsx
+import { preloadFeedAd } from '@24jieqi/react-native-brayant-ad';
+
+// 在页面进入前预加载
+useEffect(() => {
+  preloadFeedAd({
+    appid: 'your_appid',
+    codeid: 'your_codeid',
+    adWidth: '375',
+  });
+}, []);
+```
+
 ## 组件
 
 ### FeedAdView
@@ -437,6 +717,8 @@ const BannerAdPage = () => {
 
 ## 使用
 
+### 基础用法
+
 ```tsx
 import { FeedAdView } from '@24jieqi/react-native-brayant-ad';
 import { useEffect, useState } from 'react';
@@ -470,6 +752,42 @@ const RewardVideoPage = () => {
 };
 ```
 
+### 推荐用法（预加载）
+
+```tsx
+import { FeedAdView, preloadFeedAd } from '@24jieqi/react-native-brayant-ad';
+import { useEffect, useState } from 'react';
+
+const RewardVideoPage = () => {
+  const [showFeedView, setShowFeedView] = useState(false);
+
+  // 页面进入时预加载广告
+  useEffect(() => {
+    preloadFeedAd({
+      appid: 'your_appid',
+      codeid: 'your_codeid',
+    }).then(() => {
+      // 预加载成功后显示组件
+      setShowFeedView(true);
+    });
+  }, []);
+
+  return (
+    <FeedAdView
+      codeid={'your_codeid'}
+      adWidth={375}
+      visible={showFeedView}
+      onAdLayout={(data: any) => {
+        console.log('Feed 广告加载成功！', data);
+      }}
+      onAdError={(err: any) => {
+        console.log('Feed 广告加载失败！', err);
+      }}
+    />
+  );
+};
+```
+
 ## License
 
 MIT

package/android/src/main/java/com/brayantad/AdManager.java

@@ -122,6 +122,74 @@ public class AdManager extends ReactContextBaseJavaModule {
     loadTTFeedAd(codeId, width);
   }
 
+  /**
+   * 预加载信息流广告（FeedAd）
+   * 在组件渲染前调用，提前加载广告数据，减少白屏时间
+   * 与 loadFeedAd 的区别：此方法不依赖 Promise 回调，静默预加载
+   */
+  @ReactMethod
+  public void preloadFeedAd(ReadableMap options, final Promise promise) {
+    String codeId = options.getString("codeid");
+    if (codeId == null || codeId.isEmpty()) {
+      promise.reject(TAG, "codeid is required");
+      return;
+    }
+
+    float width = 0;
+    if (options.hasKey("adWidth")) {
+      width = Float.parseFloat(Objects.requireNonNull(options.getString("adWidth")));
+    }
+
+    // 检查 SDK 是否初始化
+    if (DyADCore.TTAdSdk == null) {
+      promise.reject(TAG, "TTAdSdk not initialized");
+      return;
+    }
+
+    // 如果已经有缓存的广告，直接返回成功
+    if (DyADCore.feedAd != null) {
+      promise.resolve(true);
+      return;
+    }
+
+    // 创建广告请求参数
+    float expressViewWidth = width > 0 ? width : 280;
+    float expressViewHeight = 0; // 自动高度
+
+    AdSlot adSlot = new AdSlot.Builder()
+      .setCodeId(codeId)
+      .setSupportDeepLink(true)
+      .setAdCount(1)
+      .setExpressViewAcceptedSize(expressViewWidth, expressViewHeight)
+      .setImageAcceptedSize(640, 320)
+      .setNativeAdType(AdSlot.TYPE_INTERACTION_AD)
+      .build();
+
+    // 请求广告
+    DyADCore.TTAdSdk.loadNativeExpressAd(
+      adSlot,
+      new TTAdNative.NativeExpressAdListener() {
+        @Override
+        public void onError(int code, String message) {
+          Log.d(TAG, "preloadFeedAd error: " + message);
+          promise.reject(TAG, "preload feed ad error: " + message);
+        }
+
+        @Override
+        public void onNativeExpressAdLoad(List<TTNativeExpressAd> ads) {
+          Log.d(TAG, "preloadFeedAd success");
+          if (ads == null || ads.isEmpty()) {
+            promise.reject(TAG, "preload feed ad: no ad content");
+            return;
+          }
+          // 缓存加载成功的广告
+          DyADCore.feedAd = ads.get(0);
+          promise.resolve(true);
+        }
+      }
+    );
+  }
+
   /**
    * 加载穿山甲的信息流广告
    *

package/android/src/main/java/com/brayantad/BrayantAdPackage.java

@@ -2,6 +2,7 @@ package com.brayantad;
 
 import androidx.annotation.NonNull;
 
+import com.brayantad.dy.banner.BannerAdModule;
 import com.brayantad.dy.banner.BannerAdViewManager;
 import com.brayantad.dy.drawFeed.DrawFeedViewManager;
 import com.brayantad.dy.drawFeed.DrawFeedViewModule;
@@ -29,6 +30,7 @@ public class BrayantAdPackage implements ReactPackage {
     modules.add(new RewardVideoModule(reactContext));
     modules.add(new FullScreenVideoModule(reactContext));
     modules.add(new DrawFeedViewModule(reactContext));
+    modules.add(new BannerAdModule(reactContext));
     return modules;
   }
 

package/android/src/main/java/com/brayantad/dy/DyADCore.java

@@ -70,6 +70,15 @@ public class DyADCore {
   public static CSJSplashAd splashAd;
   public static ReactContext reactContext;
 
+  // 开屏广告预加载状态管理
+  public static final int SPLASH_PRELOAD_IDLE = 0;      // 未预加载
+  public static final int SPLASH_PRELOAD_LOADING = 1;   // 预加载中
+  public static final int SPLASH_PRELOAD_SUCCESS = 2;   // 预加载成功
+  public static final int SPLASH_PRELOAD_FAIL = 3;      // 预加载失败
+  public static int splashPreloadStatus = SPLASH_PRELOAD_IDLE;
+  public static long splashPreloadTime = 0;             // 预加载成功时间戳
+  public static final long SPLASH_PRELOAD_VALID_DURATION = 5 * 60 * 1000; // 预加载有效期5分钟
+
   public static void initSdk(Context context, String appId, Boolean debug) {
     if (TTAdSdk != null && Objects.equals(tt_appid, appId)) {
       //已初始化

package/android/src/main/java/com/brayantad/dy/banner/BannerAdModule.java

@@ -0,0 +1,175 @@
+package com.brayantad.dy.banner;
+
+import android.util.Log;
+
+import androidx.annotation.NonNull;
+
+import com.brayantad.dy.DyADCore;
+import com.bytedance.sdk.openadsdk.AdSlot;
+import com.bytedance.sdk.openadsdk.TTAdNative;
+import com.bytedance.sdk.openadsdk.TTNativeExpressAd;
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+import com.facebook.react.bridge.ReadableMap;
+
+import java.util.List;
+
+/**
+ * Banner 广告预加载模块
+ * 提供 Banner 广告的预加载功能，减少白屏时间
+ */
+public class BannerAdModule extends ReactContextBaseJavaModule {
+  public static final String TAG = "BannerAdModule";
+  private static ReactApplicationContext reactAppContext;
+
+  // Banner 广告缓存
+  private static TTNativeExpressAd bannerAdCache = null;
+  private static String bannerAdCacheCodeId = null;
+  private static long bannerAdCacheTime = 0;
+  private static final long CACHE_VALID_DURATION = 5 * 60 * 1000; // 缓存有效期 5 分钟
+
+  public BannerAdModule(ReactApplicationContext reactContext) {
+    super(reactContext);
+    reactAppContext = reactContext;
+  }
+
+  @NonNull
+  @Override
+  public String getName() {
+    return TAG;
+  }
+
+  /**
+   * 预加载 Banner 广告
+   * 在组件渲染前调用，提前加载广告数据
+   *
+   * @param options 包含 codeid, adWidth, adHeight
+   * @param promise 回调
+   */
+  @ReactMethod
+  public void preloadBannerAd(ReadableMap options, final Promise promise) {
+    String codeId = options.hasKey("codeid") ? options.getString("codeid") : null;
+    int adWidth = options.hasKey("adWidth") ? options.getInt("adWidth") : 320;
+    int adHeight = options.hasKey("adHeight") ? options.getInt("adHeight") : 50;
+
+    if (codeId == null || codeId.isEmpty()) {
+      promise.reject(TAG, "codeid is required");
+      return;
+    }
+
+    // 检查 SDK 是否初始化
+    if (DyADCore.TTAdSdk == null) {
+      promise.reject(TAG, "TTAdSdk not initialized");
+      return;
+    }
+
+    // 检查缓存是否有效
+    if (hasValidCache(codeId)) {
+      Log.d(TAG, "Using cached banner ad");
+      promise.resolve(true);
+      return;
+    }
+
+    // 清除旧缓存
+    clearCache();
+
+    // 创建广告请求参数
+    AdSlot adSlot = new AdSlot.Builder()
+      .setCodeId(codeId)
+      .setSupportDeepLink(true)
+      .setAdCount(1)
+      .setExpressViewAcceptedSize(adWidth, adHeight)
+      .build();
+
+    // 请求广告
+    DyADCore.TTAdSdk.loadBannerExpressAd(
+      adSlot,
+      new TTAdNative.NativeExpressAdListener() {
+        @Override
+        public void onError(int code, String message) {
+          Log.d(TAG, "preloadBannerAd error: " + message);
+          promise.reject(TAG, "preload banner ad error: " + message);
+        }
+
+        @Override
+        public void onNativeExpressAdLoad(List<TTNativeExpressAd> ads) {
+          Log.d(TAG, "preloadBannerAd success");
+          if (ads == null || ads.isEmpty()) {
+            promise.reject(TAG, "preload banner ad: no ad content");
+            return;
+          }
+          // 缓存广告
+          bannerAdCache = ads.get(0);
+          bannerAdCacheCodeId = codeId;
+          bannerAdCacheTime = System.currentTimeMillis();
+          promise.resolve(true);
+        }
+      }
+    );
+  }
+
+  /**
+   * 检查是否有有效的缓存广告
+   *
+   * @param codeId 广告位 ID
+   * @return true 如果缓存有效
+   */
+  @ReactMethod
+  public void hasPreloadedBannerAd(String codeId, Promise promise) {
+    promise.resolve(hasValidCache(codeId));
+  }
+
+  /**
+   * 获取缓存的广告（供 BannerAdView 使用）
+   *
+   * @param codeId 广告位 ID
+   * @return 缓存的广告，如果没有则返回 null
+   */
+  public static TTNativeExpressAd getCachedBannerAd(String codeId) {
+    if (hasValidCache(codeId)) {
+      TTNativeExpressAd cachedAd = bannerAdCache;
+      // 使用后清除缓存，避免重复使用
+      clearCache();
+      return cachedAd;
+    }
+    return null;
+  }
+
+  /**
+   * 清除缓存的广告
+   */
+  @ReactMethod
+  public void clearPreloadedBannerAd() {
+    clearCache();
+  }
+
+  /**
+   * 检查缓存是否有效
+   */
+  private static boolean hasValidCache(String codeId) {
+    if (bannerAdCache == null || bannerAdCacheCodeId == null) {
+      return false;
+    }
+    // 检查 codeId 是否匹配
+    if (!bannerAdCacheCodeId.equals(codeId)) {
+      return false;
+    }
+    // 检查缓存是否过期
+    long currentTime = System.currentTimeMillis();
+    return (currentTime - bannerAdCacheTime) < CACHE_VALID_DURATION;
+  }
+
+  /**
+   * 清除缓存
+   */
+  private static void clearCache() {
+    if (bannerAdCache != null) {
+      bannerAdCache.destroy();
+      bannerAdCache = null;
+    }
+    bannerAdCacheCodeId = null;
+    bannerAdCacheTime = 0;
+  }
+}

package/android/src/main/java/com/brayantad/dy/banner/view/BannerAdView.java

@@ -9,6 +9,7 @@ import android.widget.RelativeLayout;
 
 import com.brayantad.R;
 import com.brayantad.dy.DyADCore;
+import com.brayantad.dy.banner.BannerAdModule;
 import com.brayantad.utils.Utils;
 import com.bytedance.sdk.openadsdk.AdSlot;
 import com.bytedance.sdk.openadsdk.TTAdDislike;
@@ -109,6 +110,16 @@ public class BannerAdView extends RelativeLayout {
       mBannerAd.destroy();
     }
 
+    // 先检查是否有预加载的缓存广告
+    TTNativeExpressAd cachedAd = BannerAdModule.getCachedBannerAd(mCodeId);
+    if (cachedAd != null) {
+      mBannerAd = cachedAd;
+      showBannerAd(mBannerAd);
+      mIsAdLoading = false;
+      return;
+    }
+
+    // 没有缓存，正常加载
     // 创建广告请求参数AdSlot
     mAdSlot =
       new AdSlot.Builder()