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. Forms) ,则必须在每个项目中安装包:笔记本、Android 和 iOS。 为此,您应打开每个子项目,并按照Visual Studio for MacVisual 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() 方法

添加 DistributeStart() 方法,开始 App Center 分发服务。

Xamarin.iOS

打开项目的 AppDelegate.cs 文件并在 Start() 方法中添加调用 FinishedLaunching()

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

打开项目的 MainActivity 文件,并在 Start() 方法内添加方法调用 OnCreate()

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

若要在 Android 上为调试版本启用应用内更新,请在之前调用以下方法 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 上为调试版本启用应用内更新,请在项目的 MainActivity 文件中的方法和之前调用以下方法 OnCreate LoadApplication

Distribute.SetEnabledForDebuggableBuild(true);

备注

此方法只影响调试版本,不会影响发布版本。

2.3 [仅适用于 iOS] 修改项目的 信息。 info.plist

App Center SDK 检查重定向到应用程序的 url 以避免旁加载,因此为了正确处理通过门户分发的更新,你需要 CFBundleURLSchemesCFBundleURLTypes 文件的以下部分中指定 Info.plist

备注

Info.plist,或者信息属性列表文件是结构化文本文件,其中包含捆绑的可执行文件的基本配置信息。 可以在 Apple 开发人员文档中找到有关它的详细信息。

  1. 为 info.plist (文件中的或添加新的密钥, URL types CFBundleURLTypes 如果 Xcode 将 info.plist 显示为源代码) ,则为。
  2. 将第一个子项目的键更改为 URL SchemesCFBundleURLSchemes
  3. 输入 appcenter-${APP_SECRET} 作为 URL 方案,并将替换为 ${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 与用作存根 Api 一起发布,因此,只需进行依赖关系交换即可。

  1. GooglePlay为你的 Xamarin 和共享项目添加一个名为的新生成配置。 请确保将项目生成配置正确地映射到相应的解决方案配置。 有关更多详细信息,请参阅Visual StudioVisual Studio for Mac说明。

  2. 在任何文本编辑器中打开 Xamarin 和 shared 项目 .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(...);

下面是回调实现 Xamarin.Forms 上的示例,该实现将 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 的实现说明

如示例中所示,如果回调返回 ,则必须调用 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() 当 Distribute 即将关闭时,将调用 。

应用内更新如何工作?

备注

若要使应用内更新正常工作,应从链接下载应用内部版本。 如果从 IDE 或手动安装,则它不起作用。

应用内更新功能的工作方式如下:

  1. 默认情况下,此功能仅适用于 使用 (Distribute 服务) 分发的 RELEASE 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. 将应用版本升级为 (适用于 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. OpenUrl 文件中添加 AppDelegate.cs 回调。
public override bool OpenUrl(UIApplication application, NSUrl url, string sourceApplication, NSObject annotation)
{
    Distribute.OpenUrl(url);
    return true;
}