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

App Center 散發可讓您的使用者在透過 App Center 發佈應用程式時,安裝新版本的應用程式。 使用新版本的應用程式時,SDK 將會向使用者顯示更新對話方塊,以下載或延期新的版本。 一旦選擇更新,SDK 就會開始更新您的應用程式。

警告

Google Play 將應用程式內更新程式碼視為惡意行為,即使在執行時間未使用也一樣。 將您的應用程式提交給 Google Play 之前,請依照 本節 中的指示,使用散發 SDK 的變異。 若無法移除應用程式內的更新程式碼,可能會導致應用程式不相容,且無法從 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

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

套件管理器主控台

  • Visual Studio中開啟主控台。 若要這樣做,請選擇 [工具] > NuGet 封裝管理員 > 封裝管理員主控台
  • 如果您是在 Visual Studio for Mac 中工作,請確定您已安裝 NuGet 套件管理擴充 功能。 若要這樣做,請視需要選擇 Visual Studio > 擴充 功能、搜尋 NuGet 和安裝。
  • 在主控台中輸入下列命令:
Install-Package Microsoft.AppCenter.Distribute

注意

如果您在可移植的專案中使用 App Center SDK (例如 Xamarin) ,您必須在每個專案中安裝套件:便攜、Android 和 iOS。 若要這樣做,您應該開啟每個子專案,並遵循Visual Studio for Mac或 Visual Studio 中所述的對應步驟來Windows區段。

2. 啟動 App Center 散發

若要使用 App Center,您必須選擇要使用的模組 (s) 。 依預設,不會啟動任何模組,而且您必須在啟動 SDK 時明確地呼叫每個模組。

2.1 新增 App Center 散發匯入

開始使用散發模組之前,請先新增 App Center 散發匯入:

  • Xamarin -開啟專案的檔案 AppDelegate.cs ,並將下列幾行新增至現有的 using 語句
  • Xamarin -開啟專案的檔案 MainActivity.cs ,並將下列幾行新增至現有的 using 語句下方
  • Xamarin :開啟專案的檔案 App.xaml.cs ,並將下列幾行新增至現有的 using 語句下方
using Microsoft.AppCenter;
using Microsoft.AppCenter.Distribute;

2.2 新增 Start() 方法

新增 Distribute 至您的 Start() 方法以啟動 App Center 散發服務。

Xamarin.iOS

開啟專案的檔案 AppDelegate.cs ,並在 Start() 方法內加入呼叫 FinishedLaunching()

Distribute.DontCheckForUpdatesInDebug();
AppCenter.Start("{Your Xamarin iOS App Secret}", typeof(Distribute));
Xamarin.Android

開啟專案的 >mainactivity .cs 檔案,然後在 Start() 方法內新增方法呼叫 OnCreate()

AppCenter.Start("{Your Xamarin Android App Secret}", typeof(Distribute));

若要在 Android 上啟用 debug 組建的應用程式內更新,請先呼叫下列方法 AppCenter.Start

Distribute.SetEnabledForDebuggableBuild(true);
Xamarin.Forms

若要建立以 Android 和 iOS 平臺為目標的 Xamarin. Forms 應用程式,請在 App Center 入口網站中建立兩個應用程式-每個平臺各一個。 建立兩個應用程式會提供兩個應用程式秘密-一個用於 Android,另一個用於 iOS。 開啟專案的 App.xaml.cs (或繼承自 Xamarin.Forms.Application 共用或可攜專案中) 的類別,並在覆 Start() 寫方法內新增呼叫 OnStart()

AppCenter.Start("ios={Your Xamarin iOS App Secret};android={Your Xamarin Android App secret}", typeof(Distribute));

針對您的 iOS 應用程式,在 AppDelegate.cs 呼叫 之前 ,開啟並加入下列程式 LoadApplication 程式碼:

Distribute.DontCheckForUpdatesInDebug();

在 Android 上不需要此步驟,因為在執行時間會自動偵測到偵錯工具。

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

Distribute.SetEnabledForDebuggableBuild(true);

注意

這個方法只會影響 debug 組建,而且對發行組建沒有任何影響。

2.3 [僅適用于 iOS] 請修改專案的 資訊。 plist

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

注意

Info.plist或資訊屬性清單檔案是結構化文字檔,其中包含配套可執行檔的基本設定資訊。 您可以在 Apple developer 檔中找到其詳細資訊。

  1. 在您的 plist 檔案中新增或的新金鑰 URL types CFBundleURLTypes (,以防 Xcode 將您的資訊 plist 顯示為原始程式碼) 。
  2. 將第一個子專案的索引鍵變更為 URL SchemesCFBundleURLSchemes
  3. 輸入 appcenter-${APP_SECRET} 作為 URL 配置,並取代 ${APP_SECRET} 為應用程式的應用程式密碼。

提示

如果您想要確認是否已正確修改 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 移除。 為了讓您更輕鬆,我們會提供使用 stub Api 的 App Center 散發 SDK 版本,因此您唯一的變更是相依性交換。

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

  2. 在任何文字編輯器中開啟 [ Xamarin ] 和 [共用專案] .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 頂端的命令列中變更設定。

使用私人通訊群組

依預設,「散發」會使用公用通訊群組。 如果您想要使用私人通訊群組,則必須透過屬性明確設定它 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 對話方塊取代 SDK 對話方塊的 Xamarin 形式 範例:

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 的執行附注:

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

如果您沒有呼叫 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 或以手動方式安裝,則無法運作。

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

  1. 這項功能僅適用于使用 App Center 散發 服務散發 (預設) 的 發行 組建。 如果開啟 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. 將您的應用程式 (或 iOS 版的應用程式 CFBundleShortVersionString CFBundleVersion versionCode 用於 Android)
  10. 建立應用程式的發行版本,並上傳應用程式的新組建(如同您在上一個步驟中所做的一樣),並將其散發至您稍早建立的 通訊群組 。 當應用程式下次啟動時,系統會提示通訊群組的成員輸入新版本。

提示

如需有關 通訊群組 的詳細資訊,請參閱如何 使用 App Center 散發的相關資訊。雖然您可以使用 App Center 散發來散發應用程式的新版本,而不需要新增任何程式碼,但是在應用程式的程式碼中新增 App Center 散發可讓您的測試人員和使用者獲得更順暢的體驗,因為它們會取得應用程式內的更新體驗。

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

App Center 會使用 swizzling 將應用程式委派的方法自動轉送至 App Center 服務,以改善 SDK 整合。 有可能與其他協力廠商程式庫或應用程式委派本身發生衝突。 在此情況下,您可以遵循下列步驟,停用所有 App Center 服務的 App Center 應用程式委派轉送:

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