Android

ClickForce Android SDKv3.13.0

將強大的廣告功能整合到您的 Android 應用程式中。ClickForce SDK (MFAD) 支援多種廣告形式，包括橫幅廣告、蓋板廣告、浮動廣告、影音廣告等。

支援的廣告形式

橫幅廣告、蓋板廣告、浮動廣告、Pre-Roll 影音廣告

版本記錄

此表格列出各版本的發佈與淘汰狀態，請根據您的應用版本進行相應的更新與維護。

版本 發佈日期 淘汰日期 狀態 淘汰原因
3.13.0 2025/1/1 - 支援中 -

必要條件

開發工具

  • Android Studio Ladybug 或以上版本
  • Gradle 8.6 以上版本
  • Android Gradle Plugin 8.4.0 以上版本
  • Java 17 或 Kotlin 1.9 以上版本

SDK 版本要求

  • minSdkVersion: 19 (Android 4.4)
  • targetSdkVersion: 35
  • compileSdkVersion: 35
重要提醒

請確保您的專案符合上述最低版本要求，否則 SDK 可能無法正常運作。

安裝 SDK

步驟一：加入 SDK 檔案

將 MFAD.jar 放置到專案的 app/libs/ 目錄中。

步驟二：設定 build.gradle

在 app/build.gradle 中加入以下設定：

Gradle (Groovy) 
android {
    compileSdkVersion 35
    buildToolsVersion "34.0.0"

    defaultConfig {
        minSdkVersion 19
        targetSdkVersion 35
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }

    // 啟用 Apache HTTP 支援
    useLibrary 'org.apache.http.legacy'
}

dependencies {
    // ClickForce SDK
    implementation files('libs/MFAD.jar')

    // 必要依賴
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'com.google.android.gms:play-services-ads:22.6.0'

    // Pre-Roll 廣告需要 IMA SDK
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.31.0'
}
安裝步驟

1. 下載 MFAD.jar
2. 放置到 app/libs/ 目錄
3. 在 build.gradle 加入依賴
4. Sync Project

設定權限

必要權限

在 AndroidManifest.xml 中加入以下權限：

AndroidManifest.xml 
<!-- 必要權限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<!-- 選用權限 (建議加入以提升廣告成效) -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

Google Mobile Ads 設定

如果您需要使用 AdMob 中介功能，請在 application 標籤內加入：

AndroidManifest.xml 
<application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="您的 AdMob App ID"/>
</application>

蓋板廣告

蓋板廣告以全螢幕形式呈現，支援圖片或影片素材，讓使用者能獲得更豐富的產品資訊。

AdInterstitialView API

在 Layout XML 中定義

XML 
<com.clickforce.ad.AdInterstitialView
    android:id="@+id/fullAd"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content" />

AdInterstitialListener 事件

事件 說明
onSuccessToFullAd() 廣告載入成功時觸發
onFailToFullAd() 廣告載入失敗時觸發
onClickToFullAd() 用戶點擊廣告時觸發
onCloseFullAd() 用戶關閉廣告時觸發

完整範例

Java 
import com.clickforce.ad.AdInterstitialView;
import com.clickforce.ad.Listener.AdInterstitialListener;

public class MainActivity extends AppCompatActivity {
    private AdInterstitialView fullAd;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        fullAd = findViewById(R.id.fullAd);
        fullAd.init(this);
        fullAd.outputDebugInfo = true;

        fullAd.setOnAdInterstitialListener(new AdInterstitialListener() {
            @Override
            public void onSuccessToFullAd() {
                Log.d("AD", "蓋板廣告載入成功");
                fullAd.show();
            }

            @Override
            public void onFailToFullAd() {
                Log.d("AD", "蓋板廣告載入失敗");
            }

            @Override
            public void onClickToFullAd() {
                Log.d("AD", "用戶點擊蓋板廣告");
            }

            @Override
            public void onCloseFullAd() {
                Log.d("AD", "用戶關閉蓋板廣告");
            }
        });

        fullAd.getFullScreenAd(11542);
    }
}

浮動廣告

浮動廣告可固定於螢幕特定位置，不會隨頁面滾動。

位置常數

位置 常數值
左上 AdMaglev.TOP | AdMaglev.LEFT
上方 AdMaglev.TOP
右上 AdMaglev.TOP | AdMaglev.RIGHT
左側 AdMaglev.CENTER | AdMaglev.LEFT
右側 AdMaglev.CENTER | AdMaglev.RIGHT
左下 AdMaglev.BOTTOM | AdMaglev.LEFT
下方 AdMaglev.BOTTOM
右下 AdMaglev.BOTTOM | AdMaglev.RIGHT

AdMaglevListener 事件

事件 說明
onSuccessToAdMaglev() 廣告載入成功時觸發
onFailToAdMaglev() 廣告載入失敗時觸發
onClickToAdMaglev() 用戶點擊廣告時觸發
onCloseToAdMaglev() 用戶關閉廣告時觸發

完整範例

Java 
import com.clickforce.ad.AdMaglev;
import com.clickforce.ad.Listener.AdMaglevListener;

public class MainActivity extends AppCompatActivity {
    private AdMaglev adMaglev;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // 建立右下角浮動廣告
        adMaglev = new AdMaglev(this, AdMaglev.BOTTOM | AdMaglev.RIGHT);
        adMaglev.outputDebugInfo = true;

        adMaglev.setOnAdMaglevListener(new AdMaglevListener() {
            @Override
            public void onSuccessToAdMaglev() {
                Log.d("AD", "浮動廣告載入成功");
                adMaglev.show();
            }

            @Override
            public void onFailToAdMaglev() {
                Log.d("AD", "浮動廣告載入失敗");
            }

            @Override
            public void onClickToAdMaglev() {
                Log.d("AD", "用戶點擊浮動廣告");
            }

            @Override
            public void onCloseToAdMaglev() {
                Log.d("AD", "用戶關閉浮動廣告");
            }
        });

        adMaglev.getAdMaglev(11544);
    }
}

Pre-Roll 廣告

Pre-Roll 廣告在影片播放前顯示，支援 VAST/VMAP 格式，提供更佳的廣告曝光效果。

PreRollViewLinstener 事件

事件 說明
onStartPlayVideo() 廣告開始播放時觸發
onFailedToPreRollAd() 廣告載入失敗時觸發

完整範例

Java 
import com.clickforce.ad.PreRollAdView;
import com.clickforce.ad.Listener.PreRollViewLinstener;

public class VideoActivity extends AppCompatActivity {
    private PreRollAdView preRollAdView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_video);

        preRollAdView = findViewById(R.id.preroll);
        preRollAdView.setAdTagUrl("11545");
        preRollAdView.setAdPlay(this);

        preRollAdView.setOnPreRollViewLoaded(new PreRollViewLinstener() {
            @Override
            public void onStartPlayVideo() {
                Log.d("AD", "Pre-Roll 廣告開始播放");
            }

            @Override
            public void onFailedToPreRollAd() {
                Log.d("AD", "Pre-Roll 廣告載入失敗");
                // 可在此處開始播放主影片
            }
        });
    }

    @Override
    protected void onPause() {
        super.onPause();
        if (preRollAdView != null) {
            preRollAdView.pause();
        }
    }

    @Override
    protected void onResume() {
        super.onResume();
        if (preRollAdView != null) {
            preRollAdView.resume();
        }
    }
}

常見問題

1. 為什麼廣告沒有顯示？

可能的原因：

  • 廣告 ID 錯誤：請確認廣告 ID 是否正確
  • 網路連線異常：請檢查網路狀態
  • 權限不足：請確認已加入 INTERNET 權限
  • 未呼叫 show()：廣告載入成功後需呼叫 show() 方法
  • 開啟 debug 訊息：設定 outputDebugInfo = true 以獲取詳細錯誤資訊

2. 如何開啟除錯模式？

在廣告物件上設定：

Java 
adView.outputDebugInfo = true;

3. 如何正確釋放廣告資源？

在 Activity 的 onDestroy() 中呼叫：

Java 
@Override
protected void onDestroy() {
    super.onDestroy();
    if (adView != null) {
        adView.releaseAd();
    }
}

4. ProGuard / R8 設定

如果您的專案使用 ProGuard，請加入以下規則：

ProGuard 
# ClickForce SDK
-keep class com.clickforce.ad.** { *; }
-dontwarn com.clickforce.ad.**

隱私權說明

關於資料蒐集

本 SDK 可能蒐集設備識別碼、網路連線狀態、裝置資訊及位置資訊（需用戶授權）以提供更相關的廣告。

用戶控制

用戶可透過以下方式管理隱私設定：

  • 在 Android 設定中重置廣告識別碼
  • 拒絕位置權限請求
  • 選擇退出個人化廣告

符合規範

本 SDK 遵守：

  • Google Play 開發人員政策
  • GDPR 資料保護規範
  • CCPA 隱私權要求