App Center 發佈 – Android 應用程式內更新

2025-05-06

這很重要

Visual Studio App Center 於 2025 年 3 月 31 日淘汰，但分析和診斷功能除外，這些功能將持續支援到 2026 年 6 月 30 日。瞭解更多資訊。

App Center Distribute 會在您透過 App Center 發佈新版本應用程式時，讓使用者安裝。當有新版本的應用程式可用時，SDK 會向用戶顯示更新對話框，以下載或延後新版本。一旦他們選擇更新，SDK 就會開始更新您的應用程式。

警告

Google Play 會將應用程式內更新程式代碼視為惡意行為，即使它未在運行時間使用也一樣。使用本節中指示的散發 SDK 變體，或在將應用程式提交至 Google Play 之前，先完全移除包含應用程式內更新程式碼的散發 SDK。若無法這麼做，可能會導致Google Play中的應用程式不符合規範和移除。

備註

如果您正在執行自動化UI測試，啟用的應用程式內更新將會封鎖您的自動化UI測試，因為它們會嘗試對App Center後端進行驗證。建議您不要為 UI 測試啟用 App Center Distribute。

將應用程式內更新新增至您的應用程式

如果您尚未在應用程式中設定並啟動 SDK，請遵循 [開始使用 ] 區段。

1. 加入 App Center 發佈模組

App Center SDK 是使用模組化方法所設計，開發人員只需要整合他們感興趣的服務模組。

開啟專案的 app 層級 build.gradle 檔案（app/build.gradle），並在之後 apply plugin新增下列幾行。
```
dependencies {
   def appCenterSdkVersion = '5.0.6'
   implementation "com.microsoft.appcenter:appcenter-distribute:${appCenterSdkVersion}"
}
```
備註

如果 Android Gradle 外掛程式的版本低於 3.0.0，您必須以編譯取代實作。
儲存 您的 build.gradle 檔案，並確定在 Android Studio 中觸發 Gradle 同步處理。
DownloadManager 用來下載更新。 App Center SDK 會強制執行 TLS 1.2 以改善安全性。

2.啟動 App Center 發佈

若要使用 App Center，請加入您想要使用的模組。根據預設，不會啟動任何模組，而且您必須在啟動 SDK 時明確呼叫每個模組。

將 Distribute 類別新增至方法 AppCenter.start() ，以啟動 App Center 散發服務。

AppCenter.start(getApplication(), "{Your App Secret}", Distribute.class);

AppCenter.start(application, "{Your App Secret}", Distribute::class.java)

請確定您已將上述程式碼範例中的 {Your App Secret} 替換成您的應用程式密鑰。當您將類別的引用 Distribute 新增至 start() 方法時，Android Studio 會自動建議必要的 import 陳述式，但如果您看到無法辨識類別名稱的錯誤，請將下列幾行新增至 Activity 類別中的 import 陳述式：

import com.microsoft.appcenter.AppCenter;
import com.microsoft.appcenter.distribute.Distribute;

import com.microsoft.appcenter.AppCenter
import com.microsoft.appcenter.distribute.Distribute

備註

Android 10 或更高版本對背景的啟動活動有限制。請參閱有關從背景啟動活動的限制一文。

備註

在 Android 10 上執行的應用程式（Go 版本）無法接收 SYSTEM_ALERT_WINDOW 許可權。請參閱 Go 裝置上SYSTEM_ALERT_WINDOW的相關文章。

備註

從 Android 11 開始， ACTION_MANAGE_OVERLAY_PERMISSION 意圖一律會將使用者帶到最上層的 [設定] 畫面，讓使用者可以授與或撤銷 SYSTEM_ALERT_WINDOW 應用程式的許可權。請參閱 Android 11 中許可權更新的相關文章。

準備您的Google Play組建

Google Play 會將應用程式內更新程式代碼視為惡意行為，即使它未在運行時間使用也一樣。使用本節中指示的散發 SDK 變體，或在將應用程式提交至 Google Play 之前，先完全移除包含應用程式內更新程式碼的散發 SDK。若無法這麼做，可能會導致Google Play中的應用程式不符合規範和移除。為了簡化，我們提供含有桩接 API 的 App Center Distribute SDK 版本，因此您唯一需做的變更是調整相依項目。

開啟專案的 app 層級 build.gradle 檔案（app/build.gradle）。

藉由新增產品類別來設定組建變體：

android {
    flavorDimensions "distribute"
    productFlavors {
        appCenter {
            dimension "distribute"
        }
        googlePlay {
            dimension "distribute"
        }
    }
}

修改相依性區塊，以根據產品類別取用不同的相依性：

dependencies {
    def appCenterSdkVersion = "5.0.6"
    appCenterImplementation "com.microsoft.appcenter:appcenter-distribute:${appCenterSdkVersion}"
    googlePlayImplementation "com.microsoft.appcenter:appcenter-distribute-play:${appCenterSdkVersion}"
}

儲存 您的 build.gradle 檔案，並確定在 Android Studio 中觸發 Gradle 同步處理。
您可以在 [ 建置 > 選取建置變體 ] 的下拉選單中，或工具視窗列的 [建置變體] 中變更建置變體。

您可以在 Android 檔中深入瞭解如何設定組建變體。

使用私人發佈群組

根據預設，Distribute 會使用公開散發群組。如果您想要使用私人通訊群組，您必須透過 setUpdateTrack API 明確設定它。

Distribute.setUpdateTrack(UpdateTrack.PRIVATE);

Distribute.setUpdateTrack(UpdateTrack.PRIVATE)

備註

預設值是 UpdateTrack.PUBLIC。這個方法只能在呼叫 AppCenter.start 方法之前使用。應用程式進程重新啟動時，更新追蹤的變更不會被保存，因此，如果在呼叫 `AppCenter.start` 之前沒有始終呼叫該方法，預設情況下會是公開的。

當應用程式在前景時（Distribute.setUpdateTrack(UpdateTrack.PRIVATE); 和 AppCenter.start 之後），瀏覽器視窗隨即開啟，以驗證使用者。所有後續的更新檢查都會在私有軌道上取得最新版本。

如果使用者在 私人渠道，這表示成功驗證後，他們會從自己所屬的任何私人發行群組獲得最新版本。如果使用者在 公用軌道上，這表示他們將從任何公用通訊群組取得最新版本。

禁用自動更新檢查

根據預設，SDK 會自動檢查新版本：

應用程式啟動時。
當應用程式從背景變成前景時。
啟用散發模組（如果之前已停用的話）。

如果您想要手動檢查新版本，您可以停用更新的自動檢查。若要這樣做，請在 SDK 啟動之前呼叫下列方法：

Distribute.disableAutomaticCheckForUpdate();

Distribute.disableAutomaticCheckForUpdate()

備註

此方法必須在呼叫 AppCenter.start 方法之前呼叫。

接著，您可以使用 checkForUpdate API，如下一節所述。

手動檢查更新

Distribute.checkForUpdate();

Distribute.checkForUpdate()

這會將要求傳送至 App Center，並在有新版本可用時顯示更新對話方塊。

備註

即使啟用自動更新，更新呼叫的手動檢查仍可運作。如果已完成另一項檢查，則會忽略更新的手動檢查。如果使用者已延後更新，將不會處理更新的手動檢查（除非最新版本是強制更新）。

自訂或當地語系化應用程式內更新對話方塊

1.自定義或本地化文字

如果您想要變更或本地化更新對話框中顯示的文字，您可以輕鬆地提供自己的資源字串。查看此資源檔中的字串檔案。使用相同的字串名稱/索引鍵，並指定本地化的值，使其顯示在您自己的應用程式資源檔的對話方塊中。

2.自定義更新對話框

您可以通過執行 DistributeListener 介面來客製化預設更新對話框的外觀。您需要先註冊接聽程式，再呼叫 AppCenter.start ，如下列範例所示：

Distribute.setListener(new MyDistributeListener());
AppCenter.start(...);

Distribute.setListener(MyDistributeListener())
AppCenter.start(...)

以下是接聽程式實作的範例，此實作會以自定義對話取代 SDK 對話框：

import android.app.Activity;
import android.app.AlertDialog;
import android.content.DialogInterface;
import android.net.Uri;

import com.microsoft.appcenter.distribute.Distribute;
import com.microsoft.appcenter.distribute.DistributeListener;
import com.microsoft.appcenter.distribute.ReleaseDetails;
import com.microsoft.appcenter.distribute.UpdateAction;

public class MyDistributeListener implements DistributeListener {

    @Override
    public boolean onReleaseAvailable(Activity activity, ReleaseDetails releaseDetails) {

        // Look at releaseDetails public methods to get version information, release notes text or release notes URL
        String versionName = releaseDetails.getShortVersion();
        int versionCode = releaseDetails.getVersion();
        String releaseNotes = releaseDetails.getReleaseNotes();
        Uri releaseNotesUrl = releaseDetails.getReleaseNotesUrl();

        // Build our own dialog title and message
        AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(activity);
        dialogBuilder.setTitle("Version " + versionName + " available!"); // you should use a string resource instead, this is just a simple example
        dialogBuilder.setMessage(releaseNotes);

        // Mimic default SDK buttons
        dialogBuilder.setPositiveButton(com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_download, new DialogInterface.OnClickListener() {

            @Override
            public void onClick(DialogInterface dialog, int which) {

                // This method is used to tell the SDK what button was clicked
                Distribute.notifyUpdateAction(UpdateAction.UPDATE);
            }
        });

        // We can postpone the release only if the update isn't mandatory
        if (!releaseDetails.isMandatoryUpdate()) {
            dialogBuilder.setNegativeButton(com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_postpone, new DialogInterface.OnClickListener() {

                @Override
                public void onClick(DialogInterface dialog, int which) {

                    // This method is used to tell the SDK what button was clicked
                    Distribute.notifyUpdateAction(UpdateAction.POSTPONE);
                }
            });
        }
        dialogBuilder.setCancelable(false); // if it's cancelable you should map cancel to postpone, but only for optional updates
        dialogBuilder.create().show();

        // Return true if you're using your own dialog, false otherwise
        return true;
    }
    
    @Override
    public void onNoReleaseAvailable(Activity activity) {
        Toast.makeText(activity, activity.getString(R.string.no_updates_available), Toast.LENGTH_LONG).show();
    }
}

import android.app.Activity
import android.app.AlertDialog
import com.microsoft.appcenter.distribute.Distribute
import com.microsoft.appcenter.distribute.DistributeListener
import com.microsoft.appcenter.distribute.ReleaseDetails
import com.microsoft.appcenter.distribute.UpdateAction

class MyDistributeListener : DistributeListener {

    override fun onReleaseAvailable(activity: Activity, releaseDetails: ReleaseDetails): Boolean {

        // Look at releaseDetails public methods to get version information, release notes text or release notes URL
        val versionName = releaseDetails.shortVersion
        val versionCode = releaseDetails.version
        val releaseNotes = releaseDetails.releaseNotes
        val releaseNotesUrl = releaseDetails.releaseNotesUrl

        // Build our own dialog title and message
        val dialogBuilder = AlertDialog.Builder(activity)
        dialogBuilder.setTitle("Version $versionName available!") // you should use a string resource instead, this is just a simple example
        dialogBuilder.setMessage(releaseNotes)

        // Mimic default SDK buttons
        dialogBuilder.setPositiveButton(
            com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_download
        ) { dialog, which ->
            // This method is used to tell the SDK what button was clicked
            Distribute.notifyUpdateAction(UpdateAction.UPDATE)
        }

        // We can postpone the release only if the update isn't mandatory
        if (!releaseDetails.isMandatoryUpdate) {
            dialogBuilder.setNegativeButton(
                com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_postpone
            ) { dialog, which ->
                // This method is used to tell the SDK what button was clicked
                Distribute.notifyUpdateAction(UpdateAction.POSTPONE)
            }
        }
        dialogBuilder.setCancelable(false) // if it's cancelable you should map cancel to postpone, but only for optional updates
        dialogBuilder.create().show()

        // Return true if you're using your own dialog, false otherwise
        return true
    }

    override fun onNoReleaseAvailable(activity: Activity) {
        Toast.makeText(activity, activity.getString(R.string.no_updates_available), Toast.LENGTH_LONG).show()
    }
}

如範例所示，如果您的接聽程式返回true，您必須呼叫 Distribute.notifyUpdateAction(UpdateAction.UPDATE); 或 Distribute.notifyUpdateAction(UpdateAction.POSTPONE);。

如果您未呼叫 notifyUpdateAction，則會在每次活動變更時反覆執行回調函數。

如果活動在使用者動作通知 SDK 之前變更，則可以使用相同的版本再次呼叫接聽程式。

需要此行為才能涵蓋下列案例：

您的應用程式會傳送到背景（例如按 HOME 鍵），然後在不同的活動中繼續。
您的活動是由另一個活動所涵蓋，而不需要離開應用程式（例如按下某些通知）。
其他類似的案例。

在此情況下，裝載對話框的活動可能會取代，而不需要用戶互動。因此，SDK 會再次呼叫接聽程式，以便還原自定義對話方塊。

如果 SDK 檢查更新，而且找不到比目前使用的版本更新的更新，則會從 DistributeListener 介面調用 onNoReleaseAvailable 的回調。這可讓您在這類案例中執行自定義程式碼。上述範例示範如何在找不到更新時顯示快顯通知訊息。

在執行時間啟用或停用 App Center 發行

您可以在運行時啟用或停用 App Center 的分發功能。如果停用此功能，SDK 將不會提供任何應用程式內更新功能，但您仍然可以在 App Center 入口網站中使用散發服務。

Distribute.setEnabled(false);

Distribute.setEnabled(false)

若要再次啟用App Center散發，請使用相同的API，但傳遞 true 做為參數。

Distribute.setEnabled(true);

Distribute.setEnabled(true)

狀態會保存在裝置跨應用程式啟動時的記憶體中。

此 API 是異步的，您可以在我們的 App Center 異步 API 指南中深入瞭解。

備註

只在啟動 Distribute 之後，才能使用這個方法。

檢查 App Center 分發是否已啟用

您也可以檢查 App Center 發佈是否啟用：

Distribute.isEnabled();

Distribute.isEnabled()

此 API 是異步的，您可以在我們的 App Center 異步 API 指南中深入瞭解。

備註

這個方法只能在 Distribute 已啟動後使用，開始之前它總是會傳回 false。

啟用偵錯組建的應用程式內更新

根據預設，App Center 只會針對發行組建啟用應用程式內更新。

若要在偵錯組建中啟用應用程式內更新，請在之前 AppCenter.start呼叫下列方法：

Distribute.setEnabledForDebuggableBuild(true);

Distribute.setEnabledForDebuggableBuild(true)

備註

此方法只會影響偵錯組建，而且不會影響發行組建。偵錯構建意指 android:debuggable 旗標設定為 true（通常由 gradle 預先定義的偵錯構建變體自動設定）。否則，這是發行版本。

應用程式內更新如何運作？

備註

若要讓應用程式內更新能夠運作，應該從鏈接下載應用程式組建。如果從 IDE 或手動安裝，它將無法運作。

應用程式內更新功能的運作方式如下：

這項功能僅適用於以預設方式使用 App Center Distribute 服務發佈的 RELEASE 組建。
整合 SDK 之後，建置應用程式的發行版本並上傳至 App Center，該通訊群組中的使用者將會透過電子郵件收到新版本的通知。
當使用者在其電子郵件中開啟連結時，應用程式將會安裝在其裝置上。請務必使用電子郵件連結來安裝 - 我們不支援側載。從鏈接下載應用程式時，SDK 會從 Cookie 儲存重要資訊，以便稍後檢查更新，否則 SDK 沒有該金鑰資訊。
如果應用程式將追蹤設定為私用，瀏覽器將會開啟以驗證使用者並啟用應用程式內更新。只要驗證資訊仍然有效，即使切換回公用追蹤，稍後再切換回私人，瀏覽器也不會再次開啟。如果瀏覽器驗證成功，用戶會自動重新導向回應用程式。如果曲目是公用的（這是預設值），則下一個步驟會直接執行。
應用程式的新版本會顯示應用程式內更新對話框，詢問使用者是否要更新您的應用程式：
- versionCode的較高值
- 與versionCode相等的值，但與versionName不同的值。

小提示

如果您第二次上傳相同的 APK， 對話框將不會顯示為 版本相同。

如何測試應用程式內更新？

您必須將發行組建（使用 App Center SDK 的發佈模組）上傳至 App Center 入口網站，以測試應用程式內更新，每次增加版本號碼。

如果您尚未這麼做，請在App Center入口網站中建立您的應用程式。
建立新的通訊群組並將其命名，因此您可以辨識它用於測試應用程式內更新功能。
將自己（或想要包含在應用程式內更新功能測試中的所有人員）加入。請使用新的或一次性電子郵件地址，該電子郵件地址未曾用於 App Center 上的該應用程式。這可確保您的體驗接近實際測試人員的體驗。
建立應用程式的新組建，其中包含 App Center散發 ，並包含如上所述的設定邏輯。如果群組是私人的，請勿忘記在開始使用 setUpdateTrack API 之前，先設定應用程式內私人更新追蹤。
按兩下入口網站中的 [ 發佈新版本 ] 按鈕，並上傳應用程式的組建。
上傳完成後，點擊 [下一步]，然後選取您建立的通訊群組作為該應用程式的散發目的地。
檢閱 [散發] 並將組建發佈至您的應用程式內測試群組。
該群組中的人員將會收到成為應用程式測試人員的邀請。一旦他們接受邀請，他們就可以從其行動裝置從 App Center 入口網站下載應用程式。安裝應用程式內更新之後，您就可以測試應用程式內更新。
將您的應用程式的versionCode進行更新。
建置應用程式的發行版本，並上傳您應用程式的新組建，就像您在上一個步驟中所做的一樣，並將它散發至您稍早建立的 通訊群組 。當應用程式下次啟動時，通訊群組的成員將會收到提示更新到新版本。

小提示

請查看如何使用 App Center散發的相關信息，以取得 有關通訊群組 等的詳細資訊。雖然您可以使用App Center Distribute 來發布新版本的應用程式，而不新增任何程式代碼，但將App Center Distribute 新增至應用程式程序代碼，將會導致測試人員和使用者在取得應用程式內更新體驗時，獲得更順暢的體驗。