Cordova 用戶端 SDK

發行項
07/18/2024

重要

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

此外掛程式提供 CodePush 服務的用戶端整合，可讓您輕鬆地將動態更新體驗新增至 Cordova 應用程式。

注意

Cordova Apps 的支援已於 2022 年 4 月結束。在 App Center 部落格中尋找詳細資訊。

如何運作？

Cordova 應用程式是由 HTML、CSS 和 JavaScript 檔案和任何隨附的影像所組成，這些影像由 Cordova CLI 組合在一起，並散發為平臺特定二進位檔的一部分（也就是 .ipa 或 .apk 檔案）。發行應用程式之後，更新程式代碼或映像資產會要求您重新編譯並重新發佈整個二進位檔。此程式包含您要發行之市集的檢閱時間。

CodePush 外掛程式可藉由將程式代碼和影像與發行至 CodePush 伺服器的更新保持同步，協助您立即在使用者面前改善產品。如此一來，您的應用程式就會獲得離線行動體驗的優點，以及一旦提供側載更新的「類似Web」靈活度。這是雙贏局面！

為了確保您的終端使用者一律擁有應用程式的正常運作版本，CodePush 外掛程式會維護先前更新的複本，如此一來，當您不小心推送包含當機的更新時，它會自動回復。如此一來，您就可以放心，在有機會在伺服器上復原之前，新發現的發行靈活度不會造成使用者遭到封鎖。這是一個雙贏！

注意

觸控原生程式代碼的任何產品變更（例如升級 Cordova 版本、新增外掛程式）都無法透過 CodePush 散發，因此必須透過適當的存放區更新。

支援的 Cordova 平臺

完全支援 Cordova 5.0.0+ ，以及下列相關聯的平臺：

Android （cordova-android 4.0.0+） - 包括 CrossWalk！
iOS （cordova-ios 3.9.0+） - （若要搭配cordova-plugin-wkwebview-engine外掛程式使用 CodePush，您需要安裝 v1.5.1-beta+，其中包括使用任一 WebView 的應用程式完整支援。

若要檢查您目前使用的每個 Cordova 平臺版本，您可以執行下列命令並檢查 Installed platforms 清單：

    cordova platform ls

如果您執行的 Android 或 iOS 平臺比上述還要舊，而且會開放升級，您可以執行下列命令來輕鬆執行此作業（如果不需要的話，請省略平臺）：

    cordova platform update android
    cordova platform update ios

開始使用

注意

本文包含字詞允許清單的參考，該字詞Microsoft不再使用。從軟體中移除該字詞時，我們也會將其從本文中移除。

遵循設定 CodePush 帳戶的一般用途「開始使用」指示後，您可以從應用程式的根目錄中執行下列命令，以啟動 CodePush-ifying 您的 Cordova 應用程式：

cordova plugin add cordova-plugin-code-push@latest

安裝 CodePush 外掛程式之後，請設定您的應用程式，以透過下列步驟使用它：

將部署金鑰新增至 config.xml 檔案，請務必為每個 Cordova 平臺包含正確的金鑰：

    <platform name="android">
        <preference name="CodePushDeploymentKey" value="YOUR-ANDROID-DEPLOYMENT-KEY" />
    </platform>
    <platform name="ios">
        <preference name="CodePushDeploymentKey" value="YOUR-IOS-DEPLOYMENT-KEY" />
    </platform>

提醒您，當您透過 CLI 建立 CodePush 應用程式時，會產生這些密鑰。如果您需要擷取它們，您可以執行 appcenter codepush deployment list -a <ownerName>/<appName> --displayKeys，並擷取您想要使用之特定部署的密鑰（例如， StagingProduction）。

重要

我們建議為 iOS 和 Android 建立個別的 CodePush 應用程式，這就是為什麼上述範例宣告 Android 和 iOS 的個別密鑰的原因。如果您只針對單一平臺進行開發，則只需要指定 Android 或 iOS 的部署密鑰，因此您不需要新增其他 <platform> 元素，如上所示。

從 1.10.0 版開始，您可以簽署更新套件組合（如需程式代碼簽署的詳細資訊，請參閱相關文件一節）。 若要啟用 Cordova 應用程式的程式代碼簽署，您應該設定公鑰，藉由在中config.xml提供下列preference設定來驗證套件組合的簽章：

    <platform name="android">
        ...
        <preference name="CodePushPublicKey" value="YOUR-PUBLIC-KEY" />
    </platform>
    <platform name="ios">
        ...
        <preference name="CodePushPublicKey" value="YOUR-PUBLIC-KEY" />
    </platform>

您可以針對每個平臺使用相同的私鑰組。

如果您在config.xml檔案中使用 <access origin="*" /> 元素，則您的應用程式已允許與 CodePush 伺服器通訊，而且您可以安全地略過此步驟。否則，請新增下列其他 <access /> 元素：

    <access origin="https://codepush.appcenter.ms" />
    <access origin="https://codepush.blob.core.windows.net" />
    <access origin="https://codepushupdates.azureedge.net" />

為了確保您的應用程式可以在符合 CSP 規範的平臺上存取 CodePush 伺服器，請將新增https://codepush.appcenter.ms至Content-Security-Policymeta檔案index.html中的標記：

    <meta http-equiv="Content-Security-Policy" content="default-src https://codepush.appcenter.ms 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *" />

最後，請仔細檢查您是否已安裝 cordova-plugin-whitelist 外掛程式（大部分的應用程式都會）。若要檢查此問題，請執行下列命令：

    cordova plugin ls

如果 cordova-plugin-whitelist 位於清單中，則您最好去。否則，請執行下列命令來新增它：

    cordova plugin add cordova-plugin-whitelist

您現在已準備好在應用程式程式代碼中使用外掛程式。如需詳細資訊，請參閱範例應用程式範例和 API 檔。

外掛程式使用方式

安裝並設定 CodePush 外掛程式後，唯一剩下的工作是將必要的程式代碼新增至您的應用程式，以控制下列原則：

何時（以及檢查更新的頻率？（e.g. app開始，以響應按兩下設定頁面中的按鈕，定期在某些固定間隔）
當有可用的更新時，如何向用戶呈現更新？若要這樣做，最簡單的方式是在應用程式的 deviceready 事件處理程式中執行下列命令：

codePush.sync();

如果有可用的更新，系統將會以無訊息方式下載，並在下次重新啟動應用程式時安裝它（由使用者明確或操作系統），這可確保使用者最不具侵入性的體驗。如果必要的可用更新，則會立即安裝，確保終端用戶儘快取得。

如果您想要讓應用程式更快速地探索更新，您也可以選擇在每次應用程式從背景繼續時呼叫 sync ，方法是將下列程式代碼（或同等專案）新增為應用程式啟動行為的一部分。您可以視需要經常呼叫 sync ，因此您呼叫的時機和位置取決於您的個人喜好設定。

document.addEventListener("resume", function () {
    codePush.sync();
});

此外，如果您想要顯示更新確認對話方塊（「使用中安裝」），請在安裝可用的更新時設定（例如強制立即重新啟動），或以任何方式自定義更新體驗，請參閱 sync 方法的 API 參考，以取得如何調整此預設行為的相關信息。

重要

雖然 Apple 的開發人員協定完全允許 JavaScript 和資產的無線更新（也就是可啟用 CodePush！），但應用程式會根據其原則顯示更新提示。因此，我們建議您在呼叫 sync時不要啟用 updateDialog App Store分散式應用程式，而Google Play和內部分散式應用程式（例如Enterprise、Fabric、HockeyApp）可以選擇啟用/自定義它。

發行更新

一旦您的應用程式已設定並散發給使用者，而且您已進行一些程式代碼或資產變更，就可以立即釋放它們！若要這樣做，最簡單的方式是使用 release-cordova CodePush CLI 中的命令，這個命令會處理準備和釋放您的 CodePush 伺服器更新。

注意

在您開始發行更新之前，請執行 appcenter login 命令來登入App Center

以最基本的形式，此命令只需要一個參數：您的擁有者名稱 + “/” + 應用程式名稱。

appcenter codepush release-cordova -a <ownerName>/<appName>
appcenter codepush release-cordova -a <ownerName>/MyApp-ios
appcenter codepush release-cordova -a <ownerName>/MyApp-android

提示

藉由使用App Center CLI set-current 函式，您不需要使用 -a 旗標來指定應用程式指示命令。

提示

發行 CodePush 更新時，您不需要在 config.xml 檔案中顛簸應用程式的版本，因為您完全不會修改二進位版本。當您升級 Cordova 或其中一個外掛程式時，您只需要顛簸此版本，此時您必須發行原生存放區的更新。 CodePush 會自動為您建立 v3的每個版本產生「標籤」，以協助您在發行歷程記錄中識別它。

release-cordova命令會啟用如此簡單的工作流程，因為它瞭解 Cordova 應用程式的標準版面配置，因此可以產生您的更新，並確切知道要上傳的檔案。此外，為了支援彈性發行策略，命令會公開許多選擇性參數， release-cordova 讓您自定義更新應該如何散發給終端使用者（例如哪些二進位版本與它相容？是否應該將版本視為必要？）。

# Release a mandatory update with a changelog
appcenter codepush release-cordova -a <ownerName>/MyApp-ios -m --description "Modified the header color"

# Release a dev Android build to 1/4 of your end users
appcenter codepush release-cordova -a <ownerName>/MyApp-android --rollout 25

# Release an update that targets users running any 1.1.* binary, as opposed to
# limiting the update to exact version name in the config.xml file
appcenter codepush release-cordova -a <ownerName>/MyApp-android --target-binary-version "~1.1.0"

# Release the update now but mark it as disabled
# so that no users can download it yet
appcenter codepush release-cordova -a <ownerName>/MyApp-ios -x

CodePush 用戶端支援差異更新，因此即使您在每個更新上發行應用程式程式代碼，您的終端使用者只會實際下載所需的檔案。此服務會自動處理此作業，讓您能夠專注於建立令人敬畏的應用程式，而我們可以擔心優化用戶下載。

如需命令運作方式 release-cordova 的詳細資訊，以及其公開的各種參數，請參閱 CLI 檔。此外，如果您想要自行處理執行 cordova prepare 命令，因此，想要比 release-cordova更有彈性的解決方案，請參閱 release 命令以取得詳細數據。

如果您遇到任何問題，或有任何問題/意見/意見反應，您可以傳送電子郵件給我們，或在此存放庫上開啟新問題，我們將回應 ASAP！另請參閱說明和意見反應。

API 參考

CodePush API 會透過全域 codePush 物件向您的應用程式公開，此物件會在事件引發之後 deviceready 可供使用。此 API 會公開下列最上層方法：

checkForUpdate：詢問 CodePush 服務，設定的應用程式部署是否有可用的更新。
getCurrentPackage：擷取目前已安裝更新的相關元數據（例如描述、安裝時間、大小）。
getPendingPackage：擷取已下載並安裝之更新的元數據，但尚未透過重新啟動套用。
notifyApplicationReady：通知 CodePush 運行時間已安裝的更新視為成功。如果您手動檢查並安裝更新（也就是不使用同步處理方法來為您處理全部更新），則必須呼叫此方法;否則 CodePush 會將更新視為失敗，並在應用程式下次重新啟動時回復至舊版。
restartApplication：立即重新啟動應用程式。如果有擱置的更新，則會立即向用戶顯示。
sync：允許檢查更新、下載並安裝更新，全都使用單一呼叫。除非您需要自定義UI或行為，否則建議大部分開發人員在將CodePush整合到其應用程式時使用此方法。

此外，下列物件和列舉也會全域公開為 CodePush API 的一部分：

InstallMode：定義更新的可用安裝模式。
LocalPackage：包含本機安裝套件的相關信息。
RemotePackage：包含可供下載之更新套件的相關信息。
SyncStatus：定義同步作業的可能中繼和結果狀態。

codePush.checkForUpdate

codePush.checkForUpdate(onSuccess, onError?, deploymentKey?: String);

查詢 CodePush 服務，以查看已設定的應用程式部署是否有可用的更新。根據預設，它會使用config.xml檔案中設定的部署密鑰，但您可以透過選擇性deploymentKey參數指定值來覆寫。當您想要動態「重新導向」使用者到特定部署時，這非常有用，例如允許透過復活日蛋或使用者設定參數「早期存取」。

更新檢查完成時，它會以兩個可能值的其中一個觸發 onUpdateCheck 回呼：

null 如果沒有可用的更新，則為。這種情況發生在下列案例中：
- 設定的部署不包含任何版本，因此沒有任何可更新的版本。
- 所設定部署內的最新版本是以與您目前執行的版本（較舊或更新版本）不同的二進位版本為目標。
- 目前執行中的應用程式已經有已設定部署的最新版本，因此不需要再次發行。
RemotePackage實例，表示可檢查及稍後下載的可用更新。

參數：

onSuccess：從伺服器接收成功回應時叫用的回呼。回呼會接收上述單一參數。
onError：發生錯誤時叫用的選擇性回呼。回呼會採用一個錯誤參數，其中包含錯誤的詳細數據。
deploymentKey：覆寫config.xml設定的選擇性部署密鑰。

使用方式範例：

codePush.checkForUpdate(function (update) {
    if (!update) {
        console.log("The app is up to date.");
    } else {
        console.log("An update is available! Should we download it?");
    }
});

codePush.getCurrentPackage

codePush.getCurrentPackage(onSuccess, onError?);

擷取有關目前安裝之「套件」的元數據（例如描述、安裝時間）。這適用於在套用更新之後顯示「新功能？」對話框，或檢查是否有等待透過繼續或重新啟動套用的擱置更新等案例。

更新擷取完成時，它會以兩個可能值的其中一個觸發 onSuccess 回呼：

null 如果應用程式目前正在從二進位檔執行 HTML 起始頁，而不是 CodePush 更新，則為。這種情況發生在下列案例中：
- 終端使用者已安裝應用程式二進位檔，但尚未安裝 CodePush 更新
- 終端使用者安裝了二進位檔的更新（例如從市集），清除舊的 CodePush 更新，並優先回到二進位檔。
LocalPackage實例，表示目前執行之 CodePush 更新的元數據。

參數：

onSuccess：收到目前執行中更新的相關元數據時所叫用的回呼。回呼會接收上述單一參數。
onError：發生錯誤時叫用的選擇性回呼。回呼會採用一個錯誤參數，其中包含錯誤的詳細數據。

範例使用方式：

codePush.getCurrentPackage(function (update) {
    if (!update) {
        console.log("No updates have been installed");
        return;
    }

    // If the current app "session" represents the first time
    // this update has run, and it had a description provided
    // with it upon release, let's show it to the end user
    if (update.isFirstRun && update.description) {
        // Display a "what's new?" modal
    }
});

codePush.getPendingPackage

codePush.getPendingPackage(onSuccess, onError?);

取得目前擱置更新的元數據（如果有的話）。如果更新已下載並安裝，但尚未透過應用程式重新啟動套用，則視為「擱置」。只有在InstallMode.ON_NEXT_RESTART呼叫 sync 或 LocalPackage.install時指定或 InstallMode.ON_NEXT_RESUME 時，更新才能處於這個狀態，而且應用程式尚未重新啟動或繼續（分別）。如果您想要判斷是否有擱置的更新，然後提示使用者是否要立即重新啟動， codePush.restartApplication以套用此方法，這個方法會很有用。

更新擷取完成時，它會以兩個可能值的其中一個觸發 onSuccess 回呼：

null 如果應用程式目前沒有擱置的更新（例如應用程式已經執行最新的可用版本）。
LocalPackage實例，表示目前擱置之 CodePush 更新的元數據。

參數：

onSuccess：收到目前擱置更新的相關元數據時所叫用的回呼。回呼會接收上述單一參數。
onError：發生錯誤時叫用的選擇性回呼。回呼會採用一個錯誤參數，其中包含錯誤的詳細數據。

範例使用方式：

codePush.getPendingPackage(function (update) {
    if (update) {
        // An update is currently pending, ask the
        // user if they want to restart
    }
});

codePush.notifyApplicationReady

codePush.notifyApplicationReady(notifySucceeded?, notifyFailed?);

通知 CodePush 執行時間，應該將全新安裝的更新視為成功，因此不需要自動用戶端回復。在更新套件組合的程式代碼中，必須呼叫這個函式。否則，當應用程式下次重新啟動時，CodePush 運行時間會假設已安裝的更新失敗，並回復至舊版。此行為存在，可協助確保您的終端使用者不會因更新中斷而遭到封鎖。

如果您使用函 sync 式，並在應用程式啟動時執行更新檢查，則不需要手動呼叫 notifyApplicationReady ，因為 sync 會為您呼叫它。此行為之所以存在，是因為假設在應用程式中呼叫時 sync ，表示成功啟動的良好近似值。

參數：

notifySucceeded：如果外掛程式成功通知，則叫用選擇性回呼。
notifyFailed：如果通知外掛程式時發生錯誤，則會叫用選擇性回呼。

codePush.restartApplication

codePush.restartApplication();

立即重新啟動應用程式。此方法適用於進階案例，而且在下列條件成立時主要很有用：

您的應用程式在呼叫或 LocalPackage.install 方法時，指定或 ON_NEXT_RESUME 的sync安裝模式值ON_NEXT_RESTART。這不會套用您的更新，直到應用程式重新啟動（由使用者或OS）或繼續，因此不會立即向用戶顯示更新。
您有應用程式特定的使用者事件（例如使用者流覽回應用程式的主路由），可讓您以不顯眼的方式套用更新，並可能會在使用者面前取得更新，而不是等到下一次重新啟動或繼續為止。

codePush.sync

codePush.sync(syncCallback?, syncOptions?, downloadProgress?, syncErrback?);

將應用程式的程式代碼和映像與最新版同步至已設定的部署。 checkForUpdate不同於方法，它會檢查是否有更新，並可讓您控制接下來要執行的動作，sync為您處理更新檢查、下載和安裝體驗。

這個方法支援兩個不同的（但可自定義的）「模式」，以輕鬆地啟用具有不同需求的應用程式：

無訊息模式（預設行為）會自動下載可用的更新，並在下次應用程式重新啟動時套用它們（例如作業系統或使用者終止，或裝置重新啟動）。如此一來，整個更新體驗就會對終端使用者「無訊息」，因為它們看不到任何更新提示或「綜合」應用程式重新啟動。
使用中模式，當有可用的更新時，會在下載之前提示使用者取得許可權，然後立即套用更新。如果使用強制旗標發行更新，使用者仍會收到有關更新的通知，但他們不會選擇忽略更新。

範例使用方式：

// Fully silent update that keeps the app in
// sync with the server, without ever
// interrupting the end user
codePush.sync();

// Active update that lets the end user know
// about each update, and displays it to them
// immediately after downloading it
codePush.sync(null, { updateDialog: true, installMode: InstallMode.IMMEDIATE });

提示

如果您想要根據使用者的裝置電池電量、網路條件等來決定是否檢查或下載可用的更新，請包裝呼叫以同步處理，以在條件中確認您只在需要時呼叫。

雖然同步處理方法嘗試輕鬆地以很少的組態執行無訊息和作用中更新，但它接受下列選擇性參數，讓您自定義上述默認行為的許多層面：

syncCallback：當同步處理程式從一個階段移至整體更新程式中的另一個階段時呼叫。使用表示目前狀態的狀態代碼來呼叫方法，而且可以是任何 SyncStatus 值。
syncOptions：設定同步作業行為的選擇性 SyncOptions 參數。
downloadProgress：從 CodePush 伺服器下載可用更新時定期呼叫。使用物件呼叫方法，其中包含下列兩個 DownloadProgress 屬性：
- totalBytes （Number） - 預期要接收此更新的位元組總數（也就是從上一個版本變更的檔案集大小）。
- receivedBytes （Number） - 到目前為止所下載的位元元數目，可用來追蹤下載進度。
syncErrback：在任何同步內部步驟發生錯誤時呼叫。使用標準 javascript Error 物件做為第一個自變數來呼叫方法。

SyncOptions

sync雖然方法會嘗試使用很少的組態輕鬆執行無訊息和作用中更新，但它會接受「選項」物件，讓您自定義上述默認行為的許多層面：

deploymentKey （字串） - 指定要查詢更新的部署密鑰。根據預設，此值衍生自 config.xml 檔案，但如果您需要動態使用不同的部署來呼叫 sync，這個選項可讓您從腳本端覆寫此值。
installMode （InstallMode） - 指定何時要安裝選擇性更新（也就是未標示為必要更新的更新）。預設為 InstallMode.ON_NEXT_RESTART。 InstallMode如需可用選項的描述及其用途，請參閱列舉參考。
mandatoryInstallMode （InstallMode） - 指定何時要安裝標示為必要更新的更新。預設為 InstallMode.IMMEDIATE。 InstallMode如需可用選項的描述及其用途，請參閱列舉參考。
minimumBackgroundDuration （數位） - 指定應用程式在重新啟動應用程式之前在背景中的最低秒數。這個屬性僅適用於使用 InstallMode.ON_NEXT_RESUME安裝的更新，而且對於在使用者面前更快取得更新很有用，而不會太模糊。默認為 0，它會在繼續之後立即套用更新，但時間長於背景中。
ignoreFailedUpdates （布林值） - 指定是否應該忽略先前在用戶端上安裝並回復可用的更新（因為 notifyApplicationReady 未成功呼叫）。預設為 true。
updateDialog （UpdateDialogOptions） - 用來判斷更新可用時是否應該向使用者顯示確認對話框的 “options” 物件，如果是的話，則會顯示要使用的字符串。默認為 null，這會停用對話方塊。將此值設定為任何 true 值會啟用具有預設字串的對話框，並將對象傳遞至此參數可啟用對話方塊，以及覆寫一或多個預設字串。

下列清單代表可用的選項及其預設值：

appendReleaseDescription （布林值） - 指出是否要將可用版本的描述附加至向用戶顯示的通知訊息。預設為 false。
descriptionPrefix （String） - 指出您想要在向用戶顯示更新通知時，以發行描述作為前置詞的字串。預設為 " Description: "。
mandatoryContinueButtonLabel （String）：用戶必須按下按鈕的文字，才能安裝強制更新。預設為 "Continue"。
mandatoryUpdateMessage （String） - 當更新指定為必要時，用來做為更新通知本文的文字。預設為 "An update is available that must be installed."。
optionalIgnoreButtonLabel （String） - 使用者可按下按鈕使用的文字，以忽略可用的選擇性更新。預設為 "Ignore"。
optionalInstallButtonLabel （String） - 使用者可按下以安裝選擇性更新按鈕的文字。預設為 "Install"。
optionalUpdateMessage （String） - 當更新為選擇性時，用來做為更新通知本文的文字。預設為 "An update is available. Would you like to install it?"。 *- updateTitle （String） - 用來做為用戶顯示之更新通知標頭的文字。預設為 "Update available"。

範例使用方式：

// Download the update silently, but install it on
// the next resume, as long as at least 5 minutes
// has passed since the app was put into the background.
codePush.sync(null, { installMode: InstallMode.ON_NEXT_RESUME, minimumBackgroundDuration: 60 * 5 });

// Download the update silently, and install optional updates
// on the next restart, but install mandatory updates on the next resume.
codePush.sync(null, { mandatoryInstallMode: InstallMode.ON_NEXT_RESUME });

// Changing the title displayed in the
// confirmation dialog of an "active" update
codePush.sync(null, { updateDialog: { title: "An update is available!" } });

// Displaying an update prompt that includes the
// description for the CodePush release
codePush.sync(null, {
   updateDialog: {
    appendReleaseDescription: true,
    descriptionPrefix: "\n\nChange log:\n"
   },
   installMode: InstallMode.IMMEDIATE
});

// Silently check for the update, but
// display a custom downloading UI
// via the SyncStatus and DownloadProgress callbacks
codePush.sync(syncStatus, null, downloadProgress);

function syncStatus(status) {
    switch (status) {
        case SyncStatus.DOWNLOADING_PACKAGE:
            // Show "downloading" modal
            break;
        case SyncStatus.INSTALLING_UPDATE:
            // Hide "downloading" modal
            break;
    }
}

function downloadProgress(downloadProgress) {
    if (downloadProgress) {
    	// Update "downloading" modal with current download %
        //console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes);
    }
}

sync您可以在您要檢查更新的任何位置呼叫方法。這可能位於 deviceready 事件處理程式、 click 按鈕的事件、定期定時器的回呼中，或對您的需求有意義的其他任何專案。 checkForUpdate如同方法，它會執行網路要求來檢查背景中的更新，因此不會影響您的UI線程或JavaScript線程的回應性。

封裝物件

checkForUpdate和 getCurrentPackage 方法會叫用成功回呼，當觸發時，會提供「封裝」物件的存取權。套件代表您的程式代碼更新，以及任何額外的元數據（例如描述，強制？）。 CodePush API 有下列封裝類型之間的差異：

LocalPackage：表示已經執行或已安裝且擱置應用程式重新啟動的已下載更新。
RemotePackage：表示尚未下載之 CodePush 伺服器上的可用更新。

LocalPackage

包含已下載到本機或已安裝之更新的詳細數據。您可以呼叫 codePush.getCurrentPackage 方法，或做為方法成功回呼 RemotePackage.download 所提供的值，來取得這個對象的實例參考。

屬性

appVersion：此套件更新適用於應用程式的原生版本。 （字串）
deploymentKey：套件的部署密鑰。 （字串）
描述：更新的描述。這是您在發行更新時在 CLI 中指定的相同值。 （字串）
failedInstall：指出是否已安裝此更新，但是否已回復。 sync方法會自動忽略先前失敗的更新，因此使用時checkForUpdate只需要擔心這個屬性。 （布林值）
isFirstRun：指出目前的應用程式執行是否為套用封裝之後的第一個旗標。 （布林值）
isMandatory：指出更新是否被視為必要。這是發行更新時在 CLI 中指定的值。 （布林值）
label：CodePush 伺服器自動提供給更新的內部標籤，例如 v5。此值可唯一識別其部署內的更新。 （字串）
packageHash：更新的SHA哈希值。 （字串）
packageSize：更新中包含的程式代碼大小，以位元組為單位。 （數位）

方法

install（installSuccess， installError， installOptions）：將此套件安裝至應用程式。安裝行為相依於提供的 installOptions。根據預設，更新套件會以無訊息方式安裝，而且應用程式會隨著下一個應用程式啟動時的新內容重載。在更新之後的第一次執行時，應用程式會等候 codePush.notifyApplicationReady() 呼叫。進行此呼叫之後，安裝作業就會被視為成功。否則，安裝作業將會標示為失敗，且應用程式會在下一次執行時還原成其舊版。

InstallOptions

介面定義數個選項來自定義安裝作業行為。

installMode：用來指定用於安裝作業的 InstallMode 。預設為 InstallMode.ON_NEXT_RESTART。
mandatoryInstallMode：當套件為必要時，用來指定用於安裝作業的 InstallMode 。預設為 InstallMode.IMMEDIATE。
minimumBackgroundDuration：如果 installMode 為 InstallMode.ON_NEXT_RESUME，則用來指定應用程式在繼續更新之前，必須在背景中的時間量。預設為 0。

範例使用方式：

// App version 1 (current version)

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onInstallSuccess = function () {
    console.log("Installation succeeded.");
};

var onPackageDownloaded = function (localPackage) {
    // Install regular updates after someone navigates away from the app for more than 2 minutes
    // Install mandatory updates after someone restarts the app
    localPackage.install(onInstallSuccess, onError, { installMode: InstallMode.ON_NEXT_RESUME, minimumBackgroundDuration: 120, mandatoryInstallMode: InstallMode.ON_NEXT_RESTART });
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        // The hash of each previously reverted package is stored for later use.
        // This way, we avoid going into an infinite bad update/revert loop.
        if (!remotePackage.failedInstall) {
            console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
            remotePackage.download(onPackageDownloaded, onError);
        } else {
            console.log("The available update was attempted before and failed.");
        }
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

//------------------------------------------------
// App version 2 (updated version)
var app = {
    onDeviceReady: function () {
        // Calling this function is required during the first application run after an update.
        // If not called, the application will be reverted to the previous version.
        window.codePush.notifyApplicationReady();
        // ...
    }
}

如需如何保護您不受錯誤更新保護的範例，請參閱 notifyApplicationReady（）檔。

RemotePackage

包含可從 CodePush 伺服器下載之更新的詳細數據。您可以在有更新時呼叫方法， codePush.checkForUpdate 以取得這個對象的實例參考。如果您使用同步 API，就不需要擔心 RemotePackage，因為它會自動為您處理下載和安裝程式。

屬性

RemotePackage會繼承與相同的所有屬性，但包含一個額外的屬性LocalPackage：

downloadUrl：套件可供下載的 URL。只有進階使用方式才需要這個屬性，因為 download 方法會自動為您處理更新的取得。 （字串）

方法

abortDownload（abortSuccess， abortError）：中止目前的下載會話，如果有的話。
download（downloadSuccess， downloadError， downloadProgress）：從 CodePush 服務下載套件更新。回downloadSuccess呼是使用LocalPackage自變數叫用，代表下載的套件。使用一個DownloadProgress參數在下載進度期間，會叫用選擇性downloadProgress回呼數次。

DownloadProgress

定義 DownloadProgress 物件的格式，用來傳送更新下載進度的定期更新通知。

屬性

totalBytes：下載更新套件的大小，以位元組為單位。（數位）
receivedBytes：已下載的位元元組數目。（數位）

範例使用方式：

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onPackageDownloaded = function (localPackage) {
    console.log("Package downloaded at: " + localPackage.localPath);
    // you can now update your application to the downloaded version by calling localPackage.install()
};

var onProgress = function (downloadProgress) {
    console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes + " bytes.");
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
        remotePackage.download(onPackageDownloaded, onError, onProgress);
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

列舉

CodePush API 包含下列「列舉」物件，可用來自定義更新體驗，而且可從物件全域 window 取得：

InstallMode

當您想要實際套用已安裝的更新，而且可以傳遞至 sync 或 LocalPackage.install 方法時，指定此列舉。包含下列值：

IMMEDIATE：更新將立即套用至執行中的應用程式。應用程式會立即以新的內容重載。
ON_NEXT_RESTART：表示您想要安裝更新，但不強制重新啟動應用程式。當應用程式「自然」重新啟動時（因為OS或使用者終止應用程式），更新將會順暢地挑選。執行無訊息更新時，這個值很適合，因為如果應用程式突然從無處重新啟動，可能會對終端使用者造成干擾，因為它們甚至不會下載更新。這是和 sync LocalPackage.install 方法所使用的預設模式。

如需如何保護您不受錯誤更新保護的範例，請參閱 notifyApplicationReady（）檔。

RemotePackage

屬性

RemotePackage會繼承與相同的所有屬性，但包含一個額外的屬性LocalPackage：

downloadUrl：套件可供下載的 URL。只有進階使用方式才需要這個屬性，因為 download 方法會自動為您處理更新的取得。 （字串）

方法

abortDownload（abortSuccess， abortError）：中止目前的下載會話，如果有的話。
download（downloadSuccess， downloadError， downloadProgress）：從 CodePush 服務下載套件更新。回downloadSuccess呼是使用LocalPackage自變數叫用，代表下載的套件。使用一個DownloadProgress參數在下載進度期間，會叫用選擇性downloadProgress回呼數次。

DownloadProgress

定義 DownloadProgress 物件的格式，用來傳送更新下載進度的定期更新通知。

# 屬性

totalBytes：下載更新套件的大小，以位元組為單位。（數位）
receivedBytes：已下載的位元元組數目。（數位）

範例使用方式：

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onPackageDownloaded = function (localPackage) {
    console.log("Package downloaded at: " + localPackage.localPath);
    // you can now update your application to the downloaded version by calling localPackage.install()
};

var onProgress = function (downloadProgress) {
    console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes + " bytes.");
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
        remotePackage.download(onPackageDownloaded, onError, onProgress);
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

列舉

CodePush API 包含下列「列舉」物件，可用來自定義更新體驗，而且可從物件全域 window 取得：

InstallMode

當您想要實際套用已安裝的更新，而且可以傳遞至 sync 或 LocalPackage.install 方法時，指定此列舉。包含下列值：

IMMEDIATE：更新將立即套用至執行中的應用程式。應用程式會立即以新的內容重載。
ON_NEXT_RESTART：表示您想要安裝更新，但不強制重新啟動應用程式。當應用程式「自然」重新啟動時（因為OS或使用者終止應用程式），更新將會順暢地挑選。執行無訊息更新時，這個值很適合，因為如果應用程式突然從無處重新啟動，可能會對終端使用者造成干擾，因為它們甚至不會下載更新。這是和 sync LocalPackage.install 方法所使用的預設模式。
ON_NEXT_RESUME：表示您想要安裝更新，但直到下一次使用者從背景繼續更新時，才想要重新啟動應用程式。如此一來，您就不會中斷其目前的會話，但您可以比等待下一個自然重新啟動更早地在他們前面取得更新。這個值適用於可在繼續時以非侵入性方式套用的無訊息安裝。

SyncStatus

定義同步作業的可能狀態。狀態有兩種類別：中繼和結果（最終）。中繼狀態代表同步作業的進度狀態，而且不是最終狀態。結果狀態代表同步作業的最終狀態。每個同步處理作業只會以一個結果狀態結束，但可以有零或多個中繼狀態。

UP_TO_DATE：應用程式已設定的部署完全為最新狀態。
UPDATE_INSTALLED：已安裝可用的更新，而且會在回呼函式傳回或下次應用程式繼續/重新啟動時立即執行，視 InstallMode 中指定的 SyncOptions而定。
UPDATE_IGNORED：應用程式有選擇性的更新，用戶選擇忽略此更新。 （這僅適用於使用時 updateDialog ）
錯誤：作業期間 sync 發生錯誤。與伺服器通訊、下載或解壓縮更新時，這可能是錯誤。控制台記錄應該包含所發生狀況的詳細資訊。在此情況下，未套用任何更新。
IN_PROGRESS：另一個同步正在執行中，因此已中止此同步處理嘗試。
CHECKING_FOR_UPDATE：正在查詢 CodePush 伺服器以進行更新。
AWAITING_USER_ACTION：有可用的更新，並向使用者顯示確認對話方塊。 （這僅適用於使用時 updateDialog ）
DOWNLOADING_PACKAGE：正在從 CodePush 伺服器下載可用的更新。
INSTALLING_UPDATE：已下載可用的更新，即將安裝。

PhoneGap 組建

此外掛程式與 PhoneGap Build 相容，並支援建立現用的 Android 和 iOS 組建。不過，為了讓 CodePush 在 Android 上計算二進位內容的哈希，PhoneGap Build 必須使用 Gradle 來建置您的應用程式，這不是其預設行為（它使用 Ant）。若要解決此問題，請將下列專案新增至專案的 config.xml 檔案中，做為專案的子 <platform name="android"> 系：

<preference name="android-build-tool" value="gradle" />

範例應用程式

Cordova 社群已親切地建立了一些令人敬畏的開放原始碼應用程式，這些應用程式可作為開發人員入門的範例。下列清單列出也使用 CodePush 的 OSS Cordova 應用程式，可用來查看其他人如何使用服務：

PGDay CodePush 示範 - Rangle.io 用於 PhoneGap Day Europe 2016 的示範應用程式。

注意

如果您已使用 CodePush 開發 Cordova 應用程式，這就是開放原始碼，請告訴我們。我們很想將此清單新增至此清單！

共用方式為

Cordova 用戶端 SDK

如何運作？

支援的 Cordova 平臺

開始使用

外掛程式使用方式

發行更新

API 參考

codePush.checkForUpdate

codePush.getCurrentPackage

codePush.getPendingPackage

codePush.notifyApplicationReady

codePush.restartApplication

codePush.sync

SyncOptions

封裝物件

LocalPackage

屬性

方法

InstallOptions

RemotePackage

屬性

方法

DownloadProgress

屬性

列舉

InstallMode

RemotePackage

屬性

方法

DownloadProgress

# 屬性

列舉

InstallMode

SyncStatus

PhoneGap 組建

範例應用程式

意見反應

其他資源