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

發行項
03/15/2024

重要

Visual Studio App Center 已排定於 2025 年 3 月 31 日淘汰。雖然您可以繼續使用 Visual Studio App Center，直到它完全淘汰為止，但有數個建議您考慮移轉至的建議替代方案。

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

警告

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

注意

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

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

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

1.新增 App Center 散發模組

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

Visual Studio for Mac

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

適用於 Windows 的 Visual Studio

開啟適用於 Windows 的 [Visual Studio]。
按兩下[檔案>開啟]，然後選擇您的解決方案。
在解決方案導覽器中，以滑鼠右鍵按兩下 [ 參考 ]，然後選擇 [ 管理 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 套件。若要這樣做，您應該開啟每個子專案，並遵循 windows Visual Studio for Mac 或 Visual 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 上啟用偵錯組建的應用程式內更新，請在方法和之前LoadApplication，於專案的 MainActivity.cs 檔案中OnCreate呼叫下列方法。

Distribute.SetEnabledForDebuggableBuild(true);

注意

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

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

App Center SDK 會檢查重新導向至應用程式的 URL 以避免側載，因此為了讓透過入口網站散發的更新正確處理，您必須在CFBundleURLTypes檔案的 Info.plist 區段中指定CFBundleURLSchemes：

注意

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

如果 Xcode 將 Info.plist 顯示為原始碼) ，請在 Info.plist 檔案中新增或 CFBundleURLTypes 的新金鑰 URL types (。
將第一個子項目的索引鍵變更為 URL Schemes 或 CFBundleURLSchemes。
輸入 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中的應用程式不符合規範和移除。為了讓您更容易，我們會提供 App Center 散發 SDK 的版本與 Stubbed API，因此您唯一的變更是相依性交換。

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

在任何文字編輯器中開啟 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 格式，請遵循移轉指示。

儲存您的變更並還原 NuGet 套件。
您可以在 IDE 頂端的命令列中變更組態。

使用私人通訊群組

根據預設，散發會使用公用通訊群組。如果您想要使用私人通訊群組，您必須透過 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
}

如此一來， OnWillExitApp() 當「散發」即將關閉時，將會叫用。

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

注意

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

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

這項功能預設僅適用於使用App Center散發服務散發的發行組建 () 。如果開啟 iOS 引導式存取功能，它將無法運作。
一旦您整合 SDK、建置應用程式的發行版本並上傳至 App Center，該通訊群組中的使用者將會透過電子郵件收到新版本的通知。
當使用者在其電子郵件中開啟連結時，應用程式將會安裝在其裝置上。請務必使用電子郵件連結來安裝 - 我們不支援側載。從鏈接下載應用程式時，SDK 會儲存來自 Cookie 的重要資訊，以便稍後檢查更新，否則 SDK 沒有該重要資訊。
如果應用程式將追蹤設定為私人，瀏覽器將會開啟以驗證使用者並啟用應用程式內更新。只要驗證資訊保持有效狀態，即使切換回公用曲目，稍後再切換回私人，瀏覽器也不會再次開啟。如果瀏覽器驗證成功，用戶會自動重新導向回應用程式。如果追蹤是公用 (，這是預設) ，則下一個步驟會直接發生。
- 在 iOS 9 和 10 上，的 SFSafariViewController 實體會在應用程式內開啟，以驗證使用者。驗證成功之後，它會自動關閉本身。
- 在 iOS 11 上，用戶體驗類似於 iOS 10，但 iOS 11 會要求使用者存取登入資訊的許可權。這是系統層級對話框，無法加以自定義。如果使用者取消對話框，他們可以繼續使用正在測試的版本，但不會取得應用程式內更新。下次啟動應用程式時，系統會要求他們再次存取登入資訊。
新版本的應用程式會顯示應用程式內更新對話方塊，要求使用者更新您的應用程式是否為：
- iOS：
  - 或的值 CFBundleShortVersionString 較高
  - 的相等值 CFBundleShortVersionString ，但的值 CFBundleVersion較高。
  - 版本相同，但組建唯一標識符不同。
- Android：
  - 或的值 versionCode 較高
  - 的相等值versionCode，但的值不同。versionName

提示

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

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

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

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

提示

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

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

App Center 使用雜亂自動將應用程式委派的方法轉送至 App Center 服務，以改善 SDK 整合。可能會與其他第三方連結庫或應用程式委派本身發生衝突。在此情況下，您可以依照下列步驟停用所有 App Center 服務的 App Center 應用程式委派轉送：

開啟專案的 Info.plist 檔案。
新增 AppCenterAppDelegateForwarderEnabled 索引鍵，並將值設定為 0。這會停用所有 App Center 服務的應用程式委派轉送。
在您的檔案中AppDelegate.cs新增OpenUrl回呼。

public override bool OpenUrl(UIApplication application, NSUrl url, string sourceApplication, NSObject annotation)
{
    Distribute.OpenUrl(url);
    return true;
}