共用方式為


App Center 發行 – MAUI 和 Xamarin 應用程式內更新

這很重要

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

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

警告

Google Play 會將應用程式內更新程式代碼視為惡意行為,即使它未在運行時間使用也一樣。 在將您的應用程式提交至 Google Play 之前,請依照 本節 的指示使用分發SDK的不同版本。 若無法移除應用程式內更新程序代碼,可能會導致Google Play中的應用程式不符合規範和移除。

備註

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

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

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

1. 加入 App Center 發佈模組

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

Visual Studio for Mac

  • 開啟 Visual Studio for Mac。
  • 按兩下 [ 檔案>開啟 ],然後選擇您的解決方案。
  • 在方案導覽器中,以滑鼠右鍵按兩下 [ 套件 ] 區段,然後選擇 [ 新增 NuGet 套件...]。
  • 搜尋 App Center,並安裝 App Center 發佈
  • 按兩下 [新增套件]。

Visual Studio for Windows

  • 開啟 Visual Studio for Windows。
  • 按兩下 [ 檔案>開啟 ],然後選擇您的解決方案。
  • 在方案導覽器中,以滑鼠右鍵按兩下 [ 參考 ],然後選擇 [ 管理 NuGet 套件]。
  • 搜尋 App Center,並安裝 Microsoft.AppCenter.Distribute

套件管理員主控台

  • Visual Studio 中開啟控制台。 若要這樣做,請選擇 [工具>][NuGet 套件管理員>套件管理員控制台]。
  • 如果您正在 Visual Studio for Mac 中工作,請確定您已安裝 NuGet 套件管理延伸模組。 為此,請選擇 Visual Studio>延伸模組,視需要搜尋 NuGet 並安裝。
  • 在控制台中輸入下列命令:
Install-Package Microsoft.AppCenter.Distribute

備註

如果您在可攜式專案中使用App Center SDK(例如 Xamarin.Forms),則必須在每個項目中安裝套件:可攜式、Android 和iOS 套件。 若要這樣做,您應該開啟每個子專案,並遵循 Visual Studio for MacVisual Studio for Windows 小節中所述的對應步驟。

備註

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

備註

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

備註

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

2.啟動 App Center 發佈

AppCenter.Start(...)中所述,呼叫 來設定App Center SDK。

針對您的 iOS 應用程式,開啟AppDelegate.cs,然後在呼叫 LoadApplication之前新增如下列一行:

Distribute.DontCheckForUpdatesInDebug();

在 Android 上不需要此步驟,因為在執行時會自動偵測除錯配置。

若要在Android上啟用偵錯組建的應用程式內更新,請在專案的 MainActivity.cs 檔案、 OnCreate 方法中和之前 LoadApplication呼叫下列方法。

Distribute.SetEnabledForDebuggableBuild(true);

備註

此方法只會影響偵錯組建,而且不會影響發行組建。

2.3 [僅適用於 iOS] 修改專案的 Info.plist

App Center SDK 會檢查重新導向至應用程式的網址以避免側載,因此為了讓透過管理平台散發的更新正確處理,您必須在CFBundleURLTypes文件中的Info.plist區段中指定CFBundleURLSchemes

備註

Info.plist或資訊屬性清單檔案是結構化文本檔,其中包含配套可執行檔的基本組態資訊。 您可以在 Apple 開發人員檔中找到其詳細資訊。

  1. 在 Info.plist 檔案中新增 或 CFBundleURLTypes 的索引鍵URL types(如果 Xcode 將 Info.plist 顯示為原始程式碼)。
  2. 將第一個子項目的索引鍵變更為 URL SchemesCFBundleURLSchemes
  3. 輸入 appcenter-${APP_SECRET} 作為網址設定,並以您應用程式的應用程式秘密取代 ${APP_SECRET}

小提示

如果您想要確認您已正確修改 Info.plist,請將其開啟為原始程式碼。 它應該包含以下條目,將${APP_SECRET}替換為您的應用程式密鑰:

<key>CFBundleURLTypes</key>
  <array>
      <dict>
          <key>CFBundleURLSchemes</key>
          <array>
              <string>appcenter-${APP_SECRET}</string>
          </array>
      </dict>
  </array>

移除針對 Google Play 組建的應用程式內更新

Google Play 會將應用程式內更新程式代碼視為惡意行為,即使它未在運行時間使用也一樣。 若無法移除應用程式內更新程序代碼,可能會導致Google Play中的應用程式不符合規範和移除。 為了簡化,我們提供含有桩接 API 的 App Center Distribute SDK 版本,因此您唯一需做的變更是調整相依項目。

  1. Xamarin.Android 和共享專案新增名為 GooglePlay 的新組建組態。 請確定專案建置組態已正確對應至適當的解決方案組態。 如需詳細資訊,請參閱 Visual StudioVisual Studio for Mac 指示。

  2. 在任何文本編輯器中開啟Xamarin.Android和共享專案的.csproj,並將分發參考移至條件項目組:

    <ItemGroup Condition=" '$(Configuration)' != 'GooglePlay' ">
        <PackageReference Include="Microsoft.AppCenter.Distribute" Version="3.3.0" />
    </ItemGroup>
    <ItemGroup Condition=" '$(Configuration)' == 'GooglePlay' ">
        <PackageReference Include="Microsoft.AppCenter.DistributePlay" Version="3.3.0" />
    </ItemGroup>
    

    備註

    如果您使用舊的 packages.config 格式來管理 NuGet 參考,您可以移轉至 PackageReference 格式,請遵循 移轉指示

  3. 儲存變更並還原 NuGet 套件。

  4. 您可以在 IDE 頂端的命令列中變更組態。

使用私人發佈群組

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

Distribute.UpdateTrack = UpdateTrack.Private;

備註

預設值是 UpdateTrack.Public。 這個屬性只能在 AppCenter.Start 方法呼叫之前更新。 應用程式進程重新啟動時,不會保存更新路徑的變更,因此,如果屬性在 AppCenter.Start 呼叫之前不一律更新,則預設為公用。

在此呼叫之後,瀏覽器視窗將會開啟以驗證使用者。 所有後續的更新檢查都會在私人軌道上取得最新版本。在應用程式啟動時,更新追蹤不會保存在 SDK 中。

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

禁用自動更新檢查

根據預設,SDK 會自動檢查新版本:

  • 應用程式啟動時。
  • 當應用程式進入背景後,再次回到前景。
  • 啟用散發模組(如果之前已停用的話)。

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

Distribute.DisableAutomaticCheckForUpdate();

備註

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

接著,您可以使用 CheckForUpdate 下一節所述的 API。

手動檢查更新

Distribute.CheckForUpdate();

備註

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

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

1.自定義或本地化文字

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

2.自定義更新對話框

您可以藉由實作 ReleaseAvailable 回呼函數來自訂預設更新對話框的外觀。 您必須在呼叫之前註冊回 AppCenter.Start 呼,如下列範例所示:

// In this example OnReleaseAvailable is a method name in same class
Distribute.ReleaseAvailable = OnReleaseAvailable;
AppCenter.Start(...);

以下是回呼實作的範例,此實作會將 SDK 對話框取代為自定義的 :

bool OnReleaseAvailable(ReleaseDetails releaseDetails)
{
    // Look at releaseDetails public properties to get version information, release notes text or release notes URL
    string versionName = releaseDetails.ShortVersion;
    string versionCodeOrBuildNumber = releaseDetails.Version;
    string releaseNotes = releaseDetails.ReleaseNotes;
    Uri releaseNotesUrl = releaseDetails.ReleaseNotesUrl;

    // custom dialog
    var title = "Version " + versionName + " available!";
    Task answer;

    // On mandatory update, user can't postpone
    if (releaseDetails.MandatoryUpdate)
    {
        answer = Current.MainPage.DisplayAlert(title, releaseNotes, "Download and Install");
    }
    else
    {
        answer = Current.MainPage.DisplayAlert(title, releaseNotes, "Download and Install", "Maybe tomorrow...");
    }
    answer.ContinueWith((task) =>
    {
        // If mandatory or if answer was positive
        if (releaseDetails.MandatoryUpdate || (task as Task<bool>).Result)
        {
            // Notify SDK that user selected update
            Distribute.NotifyUpdateAction(UpdateAction.Update);
        }
        else
        {
            // Notify SDK that user selected postpone (for 1 day)
            // This method call is ignored by the SDK if the update is mandatory
            Distribute.NotifyUpdateAction(UpdateAction.Postpone);
        }
    });

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

Xamarin.Android 的實作注意事項:

如範例所示,如果回調傳回true,您必須呼叫 Distribute.NotifyUpdateAction(UpdateAction.UPDATE);Distribute.NotifyUpdateAction(UpdateAction.POSTPONE);

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

在活動於使用者動作通知 SDK 之前發生變更的情況下,可以再次使用相同的版本來呼叫該回呼。

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

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

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

3.如果找不到任何更新,請執行程序代碼

當 SDK 檢查更新時,如果找不到比當前使用版本更新的版本,則會觸發 NoReleaseAvailable 回呼。 這可讓您在這類案例中執行自定義程式碼。 您必須在呼叫之前註冊回 AppCenter.Start 呼,如下列範例所示:

// In this example OnNoReleaseAvailable is a method name in same class
Distribute.NoReleaseAvailable = OnNoReleaseAvailable;
AppCenter.Start(...);
void OnNoReleaseAvailable()
{
    AppCenterLog.Info(LogTag, "No release available callback invoked.");
}

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

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

Distribute.SetEnabledAsync(false);

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

Distribute.SetEnabledAsync(true);

您不需要等候此呼叫,即可讓其他 API 呼叫 (例如) IsEnabledAsync保持一致。

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

備註

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

檢查 App Center 分發是否已啟用

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

bool enabled = await Distribute.IsEnabledAsync();

備註

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

在應用程式關閉以進行更新之前,立即執行清除 (僅限 iOS)

註冊回調函數,如下列範例所示:

// In this example, OnWillExitApp is a method name in same class
Distribute.WillExitApp = OnWillExitApp;
void OnWillExitApp()
{
    // Perform clean up here
}

如此一來,當 Distribute 即將關閉時,將會叫用 OnWillExitApp()

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

備註

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

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

  1. 這項功能僅適用於由 App Center 分發 服務所分發的 RELEASE 組建(預設)。 如果開啟 iOS 引導式存取功能,將無法運作。

  2. 整合 SDK 之後,建置應用程式的發行版本並上傳至 App Center,該通訊群組中的使用者將會透過電子郵件收到新版本的通知。

  3. 當使用者在其電子郵件中開啟連結時,應用程式將會安裝在其裝置上。 請務必使用電子郵件連結來安裝 - 我們不支援側載。 從鏈接下載應用程式時,SDK 會從 Cookie 儲存重要資訊,以便稍後檢查更新,否則 SDK 沒有該金鑰資訊。

  4. 如果應用程式將追蹤設定為私用,瀏覽器將會開啟以驗證使用者並啟用應用程式內更新。 只要驗證資訊仍然有效,即使切換回公用追蹤,稍後再切換回私人,瀏覽器也不會再次開啟。 如果瀏覽器驗證成功,用戶會自動重新導向回應用程式。 如果曲目是公用的(這是預設值),則下一個步驟會直接執行。

    • 在 iOS 9 和 10 上,會在應用程式內開啟 實例 SFSafariViewController 來驗證使用者。 驗證成功之後,它會自動關閉本身。
    • 在 iOS 11 上,用戶體驗類似於 iOS 10,但 iOS 11 會要求使用者有權存取登入資訊。 這是系統層級對話框,無法自定義。 如果使用者取消對話框,他們可以繼續使用他們正在測試的版本,但不會取得應用程式內更新。 下次啟動應用程式時,系統會要求他們再次存取登入資訊。
  5. 應用程式的新版本會顯示應用程式內更新對話框,詢問使用者是否要更新您的應用程式:

    • iOS:

      • CFBundleShortVersionString的較高值
      • 相等值 CFBundleShortVersionString ,但 值 CFBundleVersion較高。
      • 版本相同,但組建唯一標識符不同。
    • Android:

      • versionCode的較高值
      • versionCode相等的值,但與versionName不同的值。

小提示

如果您第二次上傳相同的 apk/ipa,由於二進位檔相同,對話框將不會出現。 在 iOS 上,如果您上傳具有相同版本屬性 的新 組建,則會顯示更新對話方塊。 這是因為它是 不同的 二進位檔。 在Android上,如果兩個版本屬性都相同,二進位檔會視為相同。

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

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

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

小提示

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

停用應用程式委派方法的自動轉送至 App Center 服務

App Center 使用方法交換技術,將應用程式委派的方法自動轉送至 App Center 服務,以改善 SDK 整合。 可能會與其他第三方程式庫或應用程式的委派物件發生衝突。 在此情況下,您可以遵循下列步驟,停用所有 App Center 服務的 App Center 應用程式委派轉送:

  1. 開啟專案的 Info.plist 檔案。
  2. 新增 AppCenterAppDelegateForwarderEnabled 索引鍵,並將值設定為 0。 這會停用所有 App Center 服務的應用程式委派轉送。
  3. 在您的 AppDelegate.cs 檔案中新增 OpenUrl 回呼函數。
public override bool OpenUrl(UIApplication application, NSUrl url, string sourceApplication, NSObject annotation)
{
    Distribute.OpenUrl(url);
    return true;
}