Cordova 用戶端 SDK

重要

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

深入瞭解支持時程表和替代方案。

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

注意

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

如何運作？

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

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

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

注意

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

支援的 Cordova 平臺

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

• Android (cordova-android 4.0.0+) - 包括 CrossWalk！
• iOS (cordova-ios 3.9.0+) - (若要搭配外掛程式使用 CodePush cordova-plugin-wkwebview-engine ，您需要安裝 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 外掛程式之後，請透過下列步驟設定您的應用程式來使用它：

1. 將部署金鑰新增至 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，並擷取您想要使用之特定部署的密鑰 (，例如 Staging、 Production) 。

重要

我們建議為 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>

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

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

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

1. 若要確保您的應用程式可以在 符合 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 *" />

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

    cordova plugin ls    

如果 cordova-plugin-whitelist 位於清單中，則您可以繼續。 否則，請執行下列命令以新增它：

    cordova plugin add cordova-plugin-whitelist

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

外掛程式使用方式

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

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

codePush.sync();

如果更新可供使用，則會以無訊息方式下載，並在下次重新啟動應用程式時安裝， (終端使用者或OS) 明確重新啟動，這可確保終端使用者最不具入侵的體驗。 如果必要的可用更新，則會立即安裝，以確保終端用戶儘快取得。

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

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

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

重要

雖然 Apple 的開發人員合約 完全允許 JavaScript 和資產的無線更新 (這是啟用 CodePush！) 的功能，但應用程式會針對其原則顯示更新提示。 因此，我們建議在呼叫 sync時，App Store 分散式應用程式不會啟用 updateDialog 選項，而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 或其中一個外掛程式時，您只需要升級此版本，此時您必須發行原生存放區的更新， (s) 。 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 運行時間已安裝的更新視為成功。 如果您要手動檢查並安裝更新 (，亦即不使用 sync 方法來處理您) 的所有更新， 則必須 呼叫此方法;否則，CodePush 會將更新視為失敗，並在應用程式下次重新啟動時回復至舊版。
• restartApplication：立即重新啟動應用程式。 如果有擱置的更新，則會立即向用戶顯示。
• sync：允許檢查是否有更新、下載並安裝更新，全都使用單一呼叫。 除非您需要自定義UI或行為，否則我們建議大部分的開發人員在將CodePush整合到其應用程式中時使用此方法。

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

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

codePush.checkForUpdate

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

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

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

1. null 如果沒有可用的更新，則為 。 發生於下列案例中：
   • 設定的部署不包含任何版本，因此不會更新任何版本。
   • 所設定部署內的最新版本是以與您目前執行 (較舊或更新版本) 不同的二進位版本為目標。
   • 目前執行中的應用程式已經有已設定部署的最新版本，因此不需要再次發行。
2. 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 回呼：

1. null 如果應用程式目前正在從二進位檔執行 HTML 起始頁，而不是 CodePush 更新，則為 。 發生於下列案例中：
   • 終端使用者已安裝應用程式二進位檔，且尚未安裝 CodePush 更新
   • 終端使用者安裝了二進位 (的更新，例如從存放區) 清除舊的 CodePush 更新，並將優先順序傳回二進位檔。
2. 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 或 時指定了 或 InstallMode.ON_NEXT_RESUMELocalPackage.install，而且應用程式尚未) 分別重新啟動或繼續 (，則更新只能處於此狀態。 如果您想要判斷是否有擱置的更新，然後提示使用者是否要 (透過 codePush.restartApplication) 立即重新啟動以套用它，這個方法會很有用。

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

1. null 如果應用程式目前沒有擱置的更新 (，例如應用程式已經執行最新的可用版本) 。
2. 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式，並在應用程式啟動時執行更新檢查，則不需要手動呼叫 ，因為 sync 會為您呼叫notifyApplicationReady它。 之所以存在這種行為，是因為假設在應用程式中呼叫 時 sync ，代表成功啟動的良好近似值。

參數：

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

codePush.restartApplication

codePush.restartApplication();

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

1. 當呼叫 或 LocalPackage.install 方法時，您的應用程式會指定 或 ON_NEXT_RESUME 的sync安裝模式值ON_NEXT_RESTART。 這不會套用您的更新，直到使用者或OS) 或繼續重新啟動應用程式 (，因此不會立即向用戶顯示更新。
2. 您有應用程式特定的使用者事件 (例如，終端使用者流覽回應用程式的首頁路由) ，可讓您以不干擾的方式套用更新，而且可能會在使用者前面比等到下一次重新啟動或繼續之前取得更新。

codePush.sync

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

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

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

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

範例使用方式：

// 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 (String) - 指定要查詢更新的部署密鑰。 根據預設，這個值衍生自 config.xml 檔案，但如果您需要針對 特定呼叫 sync動態使用不同的部署，此選項可讓您從腳本端覆寫此值。
• installMode (InstallMode) - 指定何時要安裝選擇性更新 (，也就是未標示為強制) 的更新。 預設值為 InstallMode.ON_NEXT_RESTART。 InstallMode如需可用選項的描述及其用途，請參閱列舉參考。
• mandatoryInstallMode (InstallMode) - 指定何時要安裝標示為強制的更新。 預設值為 InstallMode.IMMEDIATE。 InstallMode如需可用選項的描述及其用途，請參閱列舉參考。
• minimumBackgroundDuration (Number) - 指定在重新啟動應用程式之前，應用程式在背景中的最小秒數。 此屬性僅適用於使用 InstallMode.ON_NEXT_RESUME安裝的更新，而且在終端使用者前面取得更新時可能很有用，而不會太模糊。 默認為 0，它會在繼續之後立即套用更新，但長時間是在背景中。
• ignoreFailedUpdates (布爾值) - 指定如果先前已安裝並回復用戶端 (，是否應該忽略可用的更新，因為 notifyApplicationReady 未成功呼叫) 。 預設值為 true。
• updateDialog (UpdateDialogOptions) - 用來判斷更新可用時，是否應該向使用者顯示確認對話方塊的 「選項」物件，如果是的話，要使用哪些字元串。 默認為 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 方法會叫用成功回呼，當觸發時，會提供「封裝」物件的存取權。 套件代表您的程式代碼更新，以及任何額外的元數據 (，例如 description、mandatory？) 。 CodePush API 有下列套件類型之間的差異：

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

LocalPackage

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

屬性

• appVersion：此套件更新適用於的應用程式原生版本。 (字串)
• deploymentKey：套件的部署密鑰。 (字串)
• description：更新的描述。 當您發行更新時，這是您在 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) ：如果有的話，中止目前的下載會話。
• 下載 (downloadSuccess、downloadError、downloadProgress) ：從 CodePush 服務下載套件更新。 使用 LocalPackage 自變數叫用回downloadSuccess呼，代表下載的套件。 選擇性 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 方法時，指定這個列舉。 其中包含下列值：

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

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

RemotePackage

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

屬性

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

• downloadUrl：套件可供下載的 URL。 這個屬性僅適用於進階用法，因為 download 方法會自動為您處理更新的取得。 (字串)

方法

• abortDownload (abortSuccess、 abortError) ：如果有的話，中止目前的下載會話。
• 下載 (downloadSuccess、downloadError、downloadProgress) ：從 CodePush 服務下載套件更新。 使用 LocalPackage 自變數叫用回downloadSuccess呼，代表下載的套件。 選擇性 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 方法時，指定這個列舉。 其中包含下列值：

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

SyncStatus

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

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

PhoneGap 組建

此外掛程式與 PhoneGap 組建相容，並支援現用建立 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 應用程式，這就是開放原始碼，請告訴我們。 我們很樂於將它新增至此清單！