React Native 用戶端 SDK API 參考

發行項
03/21/2024

重要

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

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

CodePush 外掛程式是由兩個元件所組成：

JavaScript 模組，可匯入/需要，並允許應用程式在運行時間期間與服務互動 (，例如檢查更新、檢查目前執行中應用程式更新的元數據) 。
原生 API (Objective-C 和 Java) ，可讓 React Native 應用程式主機使用正確的 JS 套件組合位置自行啟動程式。

下列各節將詳細說明這些 API 的形狀和行為：

JavaScript API 參考

當您需要 react-native-code-push時，模組物件除了根層級元件裝飾專案之外，還會提供下列最上層方法：

allowRestart：如果擱置的更新嘗試在不允許重新啟動時嘗試重新啟動應用程式，則允許以程序設計方式重新啟動，並選擇性地重新啟動應用程式。這個方法是進階 API，只有在您的應用程式透過方法明確不允許重新啟動 disallowRestart 時才需要。
checkForUpdate：詢問 CodePush 服務是否已提供已設定的應用程式部署更新。
disallowRestart：暫時不允許因為安裝 CodePush 更新而發生任何程序設計重新啟動。此方法是進階 API，而且當應用程式內的元件 (例如上線程式時，) 需要確保使用者在其存留期內不會發生任何中斷。
getCurrentPackage：擷取目前已安裝之更新 (的相關元數據，例如描述、安裝時間、大小) 。

注意

v1.10.3-beta從 CodePush 模組起，getCurrentPackage已被取代為 getUpdateMetadata*。
getUpdateMetadata：擷取已安裝更新 (的元數據，例如描述、強制) 。
notifyAppReady：通知 CodePush 運行時間已安裝的更新視為成功。如果您手動檢查並安裝更新， (未使用同步處理方法來為您處理所有更新) ， 則必須 呼叫此方法;否則，CodePush 會將更新視為失敗，並在應用程式下次重新啟動時回復至舊版。
restartApp：立即重新啟動應用程式。如果有擱置中的更新，則會立即向用戶顯示。否則，呼叫這個方法的行為與用戶終止並重新啟動程序的行為相同。
同步處理：允許檢查更新、下載並安裝更新，全都使用單一呼叫。除非您需要自定義UI或行為，否則我們建議大部分的開發人員在將CodePush整合到其應用程式中時使用此方法

codePush

// Wrapper function
codePush(rootComponent: React.Component): React.Component;
codePush(options: CodePushOptions)(rootComponent: React.Component): React.Component;

// Decorator; Requires ES7 support
@codePush
@codePush(options: CodePushOptions)

用來將 React元件包裝在「較高順序」React元件內，該元件知道如何在掛接時同步處理應用程式的 JavaScript 套件組合和映像資產。在內部，較高順序的元件會在其componentDidMount生命週期句柄內呼叫sync，它會執行更新檢查、如果更新存在，則會下載更新，併為您安裝更新。

此裝飾專案提供支援，可讓您自定義其行為，以輕鬆啟用具有不同需求的應用程式。以下是一些您可以使用的方式範例， (您可以挑選一個或甚至使用組合) ：

應用程式上的無訊息同步處理 ( 最簡單的預設行為) 。您的應用程式會自動下載可用的更新，並在下次應用程式重新啟動 (時套用它們，例如操作系統或使用者終止它，或裝置) 重新啟動。如此一來，用戶的整個更新體驗會「無訊息」，因為它們不會看到任何更新提示或「綜合」應用程式重新啟動。
```
// Fully silent update that keeps the app in
// sync with the server, without ever
// interrupting the end user
class MyApp extends Component {}
MyApp = codePush(MyApp);
```

每次應用程式繼續時，都會進行無訊息同步處理。與 1 相同，不同之處在於我們會檢查更新，或在每次應用程式在「背景」之後返回前景時套用更新。

// Sync for updates every time the app resumes.
class MyApp extends Component {}
MyApp = codePush({ checkFrequency: codePush.CheckFrequency.ON_APP_RESUME, installMode: codePush.InstallMode.ON_NEXT_RESUME })(MyApp);

互動式。當有可用的更新時，請先提示使用者提供許可權，再下載，然後立即套用更新。如果使用旗標發行 mandatory 更新，使用者仍會收到更新的相關通知，但無法選擇忽略更新。

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

記錄/顯示進度。當應用程式與伺服器同步以進行更新時，請使用 codePushStatusDidChange 或 codePushDownloadDidProgress 事件勾點來記錄此程式的不同階段，甚至向使用者顯示進度列。

// Make use of the event hooks to keep track of
// the different stages of the sync process.
class MyApp extends Component {
    codePushStatusDidChange(status) {
        switch(status) {
            case codePush.SyncStatus.CHECKING_FOR_UPDATE:
                console.log("Checking for updates.");
                break;
            case codePush.SyncStatus.DOWNLOADING_PACKAGE:
                console.log("Downloading package.");
                break;
            case codePush.SyncStatus.INSTALLING_UPDATE:
                console.log("Installing update.");
                break;
            case codePush.SyncStatus.UP_TO_DATE:
                console.log("Up-to-date.");
                break;
            case codePush.SyncStatus.UPDATE_INSTALLED:
                console.log("Update installed.");
                break;
        }
    }

    codePushDownloadDidProgress(progress) {
        console.log(progress.receivedBytes + " of " + progress.totalBytes + " received.");
    }
}
MyApp = codePush(MyApp);

CodePushOptions

codePush裝飾專案接受「選項」物件，可讓您自定義上述預設行為的許多層面：

checkFrequency (codePush.CheckFrequency) - 指定何時要檢查更新。預設值為 codePush.CheckFrequency.ON_APP_START。 CheckFrequency如需可用選項的描述及其用途，請參閱列舉參考。
deploymentKey (String) - 指定要查詢更新的部署密鑰。根據預設，此值衍生自 iOS (iOS) 和 MainActivity.java 檔案 (Android) ，但如果您需要動態使用不同的部署，此選項可讓您從腳本端覆寫此值。
installMode (codePush.InstallMode) - 指定何時要安裝選擇性更新， (未標示為強制) 的更新。預設值為 codePush.InstallMode.ON_NEXT_RESTART。 InstallMode如需可用選項的描述及其用途，請參閱列舉參考。
mandatoryInstallMode (codePush.InstallMode) - 指定何時要安裝標記為強制的更新。預設值為 codePush.InstallMode.IMMEDIATE。 InstallMode如需可用選項的描述及其用途，請參閱列舉參考。
minimumBackgroundDuration (Number) - 指定在重新啟動應用程式之前，應用程式在背景中的最小秒數。此屬性僅適用於使用 InstallMode.ON_NEXT_RESUME 或 InstallMode.ON_NEXT_SUSPEND安裝的更新，而且在使用者前面更快取得更新很有用，而不會太模糊。默認為 0，這會在繼續之後立即套用更新，或除非應用程式暫停夠長，但長到背景。
updateDialog (UpdateDialogOptions) - 用來判斷更新可用時，是否應該向使用者顯示確認對話框的 “options” 物件，如果是的話，則會顯示要使用的字串。默認為 null，這會停用對話方塊。將此值設定為任何 true 值會啟用具有預設字串的對話框，並將對象傳遞至此參數可啟用對話方塊，以及覆寫一或多個預設字串。在 App Store 分散式應用程式內啟用此選項之前，請參閱此附註。

下列清單代表可用的選項及其預設值：
- 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?"。
- title (String) - 用來做為用戶顯示之更新通知標頭的文字。預設值為 "Update available"。
rollbackRetryOptions (RollbackRetryOptions) - 回復重試機制可讓應用程式嘗試重新安裝先前復原的更新， (選項) 中指定的限制。這是用來判斷是否應該發生回復重試的「選項」物件，如果是，則用於復原重試的設定。這預設為 null，這會影響停用重試機制。將此設定為任何真實值將會啟用預設設定的重試機制，並將對象傳遞至此參數可啟用復原重試，以及覆寫一或多個預設值。

下列清單代表可用的選項及其預設值：
- delayInHours (Number) - 指定應用程式在嘗試重新安裝相同回復套件之前，應用程式會在最新回復後等候的最小時間。不能小於 0。可以是浮點數。預設值為 24。
- maxRetryAttempts (Number) - 指定應用程式在停止嘗試之前可以進行的重試嘗試次數上限。不能小於 1。預設值為 1。

codePushStatusDidChange (事件攔截)

當同步處理程式從一個階段移至整體更新程式中的另一個階段時呼叫。事件攔截是使用表示目前狀態的狀態代碼來呼叫，而且可以是任何 SyncStatus 值。

codePushDownloadDidProgress (事件攔截)

從 CodePush 伺服器下載可用的更新時，定期呼叫。使用物件呼叫方法，其中包含下列兩個 DownloadProgress 屬性：

totalBytes (Number) - 預期針對此更新接收的位元組總數， (為檔案集的大小，從舊版) 變更。
receivedBytes (Number) - 到目前為止下載的位元元組數目，可用來追蹤下載進度。

codePush.allowRestart

codePush.allowRestart(): void;

會讓程式設計重新啟動發生，否則會因為先前呼叫 disallowRestart而遭到拒絕。如果 disallowRestart 從未在第一個位置呼叫，則呼叫此方法會導致無作業。

如果 CodePush 更新目前擱置中，嘗試重新啟動應用程式 (例如它使用 InstallMode.IMMEDIATE) ，但因為呼叫過而遭到封鎖 disallowRestart ，則呼叫 allowRestart 會導致立即重新啟動。此重新啟動可讓更新儘快套用，而不會在重要工作流程期間中斷使用者， (例如上線程式) 。

例如，如果呼叫之後發生disallowRestart檔中所述disallowRestart的三個案例之一，則呼叫 allowRestart 會觸發立即重新啟動。不過，如果下列幾點成立，則呼叫 allowRestart 不會觸發重新啟動：

自上次呼叫后 disallowRestart 未安裝 CodePush 更新，因此，您仍然不需要重新啟動。
目前有擱置的 CodePush 更新，但已透過 InstallMode.ON_NEXT_RESTART安裝，因此不需要程式設計重新啟動。
目前有擱置的 CodePush 更新，但已透過 InstallMode.ON_NEXT_RESUME 安裝，且應用程式尚未放入背景，因此不需要以程式設計方式重新啟動。
自上次disallowRestart呼叫後未呼叫 restartApp 。

此行為可確保除非在不允許期間明確要求重新啟動，否則不會觸發任何 allowRestart 重新啟動。如此一來， allowRestart 就類似於呼叫 restartApp(true)，但前者只會在目前擱置的更新想要重新啟動時觸發重新啟動，但後者會在更新擱置時重新啟動。

如需如何使用此方法的範例，請參閱 disallowRestart 。

codePush.checkForUpdate

codePush.checkForUpdate(deploymentKey: String = null, handleBinaryVersionMismatchCallback: (update: RemotePackage) => void): Promise<RemotePackage>;

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

第二個選擇性參數 handleBinaryVersionMismatchCallback 是選擇性回呼函式，可在有任何二進位更新時用來通知使用者。例如，請考慮使用案例，其中目前安裝的二進位版本是 1.0.1，其標籤 (程式代碼推播卷標) v1。稍後的原生程式代碼已在開發週期中變更，而二進位版本已更新為 1.0.2。觸發codepush更新檢查時，我們會忽略二進位版本不符的更新 (，因為更新不是以目前安裝之應用程式的二進位版本為目標) 。在此情況下，已安裝的應用程式 (1.0.1) 將會忽略以 1.0.2 版為目標的更新。您可以使用 handleBinaryVersionMismatchCallback 來提供勾點來處理這類情況。

重要

如果您正在開發 iOS 應用程式，因此請小心使用此回呼內的警示，因為 App Store 檢閱程式：應用程式不得強制使用者對應用程式進行評分、檢閱應用程式、下載其他應用程式，或存取功能、內容或使用應用程式的其他類似動作。

這個方法會傳回，它會解析為兩個可能值的其中一個 Promise：

null 如果沒有可用的更新，則為。這可能會在下列案例中發生：
1. 設定的部署不包含任何版本，因此不會更新任何版本。
2. 所設定部署內的最新版本是以與您目前執行 (較舊或更新版本) 不同的二進位版本為目標。
3. 目前執行中的應用程式已從設定的部署中取得最新版本，因此不需要它。
4. 已設定部署內的最新版本目前標示為已停用，因此不允許下載。
5. 已設定部署內的最新版本處於「作用中推出」狀態，而要求裝置不落在符合資格的使用者百分比內。
RemotePackage實例，表示可檢查或更新下載的可用更新。

範例使用方式：

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

codePush.disallowRestart

codePush.disallowRestart(): void;

暫時不允許因為下列任一案例而發生程式設計重新啟動：

使用安裝 CodePush 更新 InstallMode.IMMEDIATE
CodePush 更新是使用 InstallMode.ON_NEXT_RESUME 安裝，而且應用程式會從背景繼續執行， (屬性選擇性地進行 minimumBackgroundDuration 節流處理)
restartApp已呼叫方法

注意

步驟 1 和 2 可透過為您呼叫 restartApp 有效地運作，因此，不論您的應用程式是直接或間接呼叫，您都可以將其視為 disallowRestart 封鎖任何呼叫 restartApp。

呼叫此方法之後， sync 仍允許檢查更新、下載並安裝更新，但嘗試重新啟動應用程式會排入佇列，直到 allowRestart 呼叫為止。如此一來，就會擷取重新啟動要求，而且每當您想要允許它發生時，都可以「排清」。

這是進階 API，而且在應用程式內的個別元件 (例如上線程式時，) 需要確保使用者無法在其存留期內發生任何中斷，同時繼續讓應用程式以自己的步調與 CodePush 伺服器保持同步，以及使用任何適當的安裝模式。這可讓應用程式儘快探索和下載可用的更新，同時避免在關鍵用戶體驗期間發生任何中斷。

或者，您也可以在呼叫 sync (時使用InstallMode.ON_NEXT_RESTART，這永遠不會嘗試以程式設計方式重新啟動應用程式) ，然後在應用程式「安全」的點明確呼叫 restartApp 。 disallowRestart 當與 CodePush 伺服器同步的程式代碼與想要強制執行無重新啟動原則的程式代碼/元件分開時，會提供此方法的替代方法。

範例使用方式：

class OnboardingProcess extends Component {
    ...

    componentWillMount() {
        // Ensure that any CodePush updates that are
        // synchronized in the background can't trigger
        // a restart while this component is mounted.
        codePush.disallowRestart();
    }

    componentWillUnmount() {
        // Reallow restarts, and optionally trigger
        // a restart if one was currently pending.
        codePush.allowRestart();
    }

    ...
}

codePush.getCurrentPackage

注意

此方法在 CodePush 模組中被視為已被取代 v1.10.3-beta 。如果您要執行此版本 (或更新版本) ，建議您改用 codePush.getUpdateMetadata ，因為它具有更可預測的行為。

codePush.getCurrentPackage(): Promise<LocalPackage>;

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

這個方法會傳回，它會解析為兩個可能值的其中一個 Promise：

null 如果應用程式目前正在從二進位檔執行 JS 套件組合，而不是 CodePush 更新，則為。這會在下列案例中發生：
1. 終端使用者已安裝應用程式二進位檔，且尚未安裝 CodePush 更新
2. 終端使用者安裝二進位 (更新，例如，從存放區) 清除舊的CodePush更新，並將優先順序傳回二進位檔中的 JS 二進位檔。
LocalPackage實例，表示目前執行之 CodePush 更新的元數據。

範例使用方式：

codePush.getCurrentPackage()
.then((update) => {
    // 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.getUpdateMetadata

codePush.getUpdateMetadata(updateState: UpdateState = UpdateState.RUNNING): Promise<LocalPackage>;

擷取已安裝更新的元數據 (，例如描述，其狀態符合指定 updateState 參數的必要) 。這適用於在套用更新之後顯示「新功能？」對話框等案例，或檢查是否有等候透過繼續或重新啟動套用的擱置更新。如需可能更新狀態及其代表狀態的詳細資訊，請參閱 UpdateState 參考。

這個方法會傳回，它會解析為兩個可能值的其中一個 Promise：

null 如果具有指定狀態的更新目前不存在，則為。這會在下列案例中發生：
1. 終端使用者尚未安裝任何 CodePush 更新，這就是為什麼沒有任何元數據可供任何更新使用，不論您指定為 updateState 參數。
2. 終端使用者安裝二進位 (更新，例如，從存放區) 清除舊的CodePush更新，並將優先順序傳回二進位檔中的 JS 二進位檔。其會呈現與 #1 相同的行為
3. 參數 updateState 設定為 UpdateState.RUNNING，但應用程式目前未執行 CodePush 更新。可能會有擱置的更新，但應用程式尚未重新啟動，使其處於作用中狀態。
4. 參數 updateState 設定為 UpdateState.PENDING，但應用程式沒有任何目前擱置的更新。
LocalPackage實例，表示目前要求之 CodePush 更新的元數據， (執行中或擱置) 。

範例使用方式：

// Check if there's currently a CodePush update running, and if
// so, register it with the HockeyApp SDK (https://github.com/slowpath/react-native-hockeyapp)
// so that crash reports will correctly display the JS bundle version the user was running.
codePush.getUpdateMetadata().then((update) => {
    if (update) {
        hockeyApp.addMetadata({ CodePushRelease: update.label });
    }
});

// Check to see if there's still an update pending.
codePush.getUpdateMetadata(UpdateState.PENDING).then((update) => {
    if (update) {
        // There's a pending update, do we want to force a restart?
    }
});

codePush.notifyAppReady

codePush.notifyAppReady(): Promise<void>;

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

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

注意

這個方法也會別名為 notifyApplicationReady (，以便回溯兼容性) 。

codePush.restartApp

codePush.restartApp(onlyIfUpdateIsPending: Boolean = false): void;

立即重新啟動應用程式。如果提供真值給 onlyIfUpdateIsPending 參數，則只有在實際有等候套用的擱置更新時，應用程式才會重新啟動。

此方法適用於進階案例，而且在下列條件成立時主要很有用：

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

codePush.sync

codePush.sync(options: Object, syncStatusChangeCallback: function(syncStatus: Number), downloadProgressCallback: function(progress: DownloadProgress), handleBinaryVersionMismatchCallback: function(update: RemotePackage)): Promise<Number>;

將應用程式的 JavaScript 套件組合和映像資產與最新版本同步處理至已設定的部署。不同於 checkForUpdate 方法，它會檢查是否有更新，讓我們控制下一步要做什麼， sync 為您處理更新檢查、下載和安裝體驗。

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

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

範例使用方式：

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

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

提示

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

SyncOptions

sync雖然方法嘗試使用少量設定輕鬆地執行無訊息和作用中的更新，但它會接受「選項」物件，讓您自定義上述默認行為的許多層面。可用的選項與 CodePushOptions 相同，但選項除外 checkFrequency ：

deploymentKey (String) - 請參閱 CodePushOptions。
installMode (codePush.InstallMode) - 請參閱 CodePushOptions。
mandatoryInstallMode (codePush.InstallMode) - 請參閱 CodePushOptions。
minimumBackgroundDuration (Number) - 請參閱 CodePushOptions。
updateDialog (UpdateDialogOptions) - 請參閱 CodePushOptions。
rollbackRetryOptions (RollbackRetryOptions) - 請參閱 CodePushOptions。

範例使用方式：

// Use a different deployment key for this
// specific call, instead of the one configured
// in the Info.plist file
codePush.sync({ deploymentKey: "KEY" });

// 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({ installMode: codePush.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({ mandatoryInstallMode: codePush.InstallMode.ON_NEXT_RESUME });

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

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

// Shortening the retry delay and increasing
// the number of maximum retry attempts
// in comparison to defaults
codePush.sync({
   rollbackRetryOptions: {
    delayInHours: 8,
    maxRetryAttempts: 3
   }
});

除了選項之外， sync 方法也接受數個選擇性函式參數，可讓您訂閱「管線」的生命週期 sync ，視需要顯示其他UI (，例如「檢查更新強制回應或下載進度強制回應) ：

syncStatusChangedCallback ( (syncStatus：Number) => void) - 當同步處理程式從一個階段移至整體更新程式中的另一個階段時呼叫。使用狀態代碼呼叫方法，其代表目前狀態，而且可以是任何 SyncStatus 值。
downloadProgressCallback ( (進度：DownloadProgress) => void) - 從 CodePush 伺服器下載可用更新時定期呼叫。使用物件呼叫方法，其中包含下列兩個 DownloadProgress 屬性：
- totalBytes (Number) - 預期針對此更新接收的位元組總數， (為檔案集的大小，從舊版) 變更。
- receivedBytes (Number) - 到目前為止下載的位元元組數目，可用來追蹤下載進度。
handleBinaryVersionMismatchCallback ( (更新：RemotePackage) => void) - 有任何二進位更新可用時呼叫。使用物件呼叫 RemotePackage 方法。如需詳細資訊，請參閱 codePush.checkForUpdate 一節。

範例使用方式：

// Prompt the user when an update is available
// and then display a "downloading" modal
codePush.sync({ updateDialog: true },
  (status) => {
      switch (status) {
          case codePush.SyncStatus.DOWNLOADING_PACKAGE:
              // Show "downloading" modal
              break;
          case codePush.SyncStatus.INSTALLING_UPDATE:
              // Hide "downloading" modal
              break;
      }
  },
  ({ receivedBytes, totalBytes, }) => {
    /* Update download modal progress */
  }
);

這個方法會傳 Promise回，它會解析為 SyncStatus 指出呼叫成功的原因的程序 sync 代碼。此程式代碼可以是下列 SyncStatus 其中一個值：

codePush.SyncStatus.UP_TO_DATE (4) - 應用程式與 CodePush 伺服器是最新的。
codePush.SyncStatus.UPDATE_IGNORED (5) - 應用程式有選擇性的更新，終端使用者選擇忽略該更新。 (只有在使用) 時才 updateDialog 適用。
codePush.SyncStatus.UPDATE_INSTALLED (6) - 更新已安裝，且會在函式傳回之後syncStatusChangedCallback立即執行，或下次應用程式繼續/重新啟動時執行，視中指定的 SyncOptions而定InstallMode。
codePush.SyncStatus.SYNC_IN_PROGRESS (7) - 執行 sync 中的作業可防止執行目前的呼叫。

您可以在 sync 您要檢查更新的任何位置呼叫方法。這可能是在 componentWillMount 根元件的生命週期事件、元件的 onPress 處理程式 <TouchableHighlight> 、定期定時器的回呼中，或對您需求有意義的其他任何情況。 checkForUpdate如同方法，它會執行網路要求來檢查背景中的更新，因此不會影響您的UI線程或JavaScript線程的回應性。

封裝物件

checkForUpdate和 getUpdateMetadata 方法會傳回 Promise 物件，當解析時，會提供「封裝」物件的存取權。套件代表您的程式代碼更新，以及任何額外的元數據 (，例如描述，強制？) 。 CodePush API 有下列套件類型之間的差異：

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

LocalPackage

包含已下載到本機或已安裝之更新的詳細數據。您可以藉由呼叫模組層級 getUpdateMetadata 方法，或做為方法所 RemotePackage.download 傳回之 Promise 的值，來取得這個對象的實例參考。

屬性

appVersion：此更新相依的應用程式二進位版本。這是呼叫 CLI 命令release時透過參數指定的appStoreVersion值。 (字串)
deploymentKey：原本用來下載此更新的部署密鑰。 (字串)
description：更新的描述。當您發行更新時，這是您在 CLI 中指定的相同值。 (字串)
failedInstall：指出是否已安裝此更新，但已回復。方法 sync 會自動忽略先前失敗的更新，因此使用時只需要擔心這個屬性 checkForUpdate。 (布爾值)
isFirstRun：指出這是安裝之後第一次執行更新的時間。這適用於判斷您是否要顯示「新功能？」安裝更新之後，終端使用者的UI。 (布爾值)
isMandatory：指出更新是否被視為必要。這是發行更新時在 CLI 中指定的值。 (布爾值)
isPending：指出此更新是否處於「擱置中」狀態。當為時 true，這表示已下載並安裝更新，但應用程式重新啟動需要套用它尚未發生，這就是使用者目前看不到其變更的原因。 (布爾值)
label：CodePush 伺服器自動提供給更新的內部標籤，例如 v5。此值可唯一識別其部署內的更新。 (字串)
packageHash：更新的SHA哈希值。 (字串)
packageSize：更新中包含的程式代碼大小，以位元組為單位。 (數位)

方法

install (installMode： codePush.InstallMode = codePush.InstallMode.ON_NEXT_RESTART， minimumBackgroundDuration = 0) ： Promise<void>：將更新儲存到運行時間預期會尋找最新版應用程式的磁碟位置來安裝更新。參數 installMode 可控制用戶呈現變更的時機。默認值是等到下一個應用程式重新啟動以顯示變更，但您可以參考列舉參考，以取得 InstallMode 可用選項的描述及其用途。 installMode如果參數設定InstallMode.ON_NEXT_RESUME為，則 minimumBackgroundDuration 參數可讓您控制應用程式在繼續之後強制安裝之前，必須處於背景的時間長度。

RemotePackage

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

屬性

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

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

方法

下載 (downloadProgressCallback？：函式) ： Promise<LocalPackage>：從 CodePush 服務下載可用的更新。 downloadProgressCallback如果指定，則會使用物件{ totalBytes: Number, receivedBytes: Number }定期DownloadProgress呼叫， () 報告下載進度，直到完成為止。傳回使用解析的 LocalPackagePromise。

列舉

CodePush API 包含下列列舉，可用來自定義更新體驗：

InstallMode

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

codePush.InstallMode.IMMEDIATE (0) - 指出您想要安裝更新並立即重新啟動應用程式。此值適用於偵錯案例，以及向用戶顯示更新提示時，因為其預期會在接受安裝之後立即看到變更。此外，此模式可以用來強制執行強制更新，因為它會移除更新安裝與下一次使用者重新啟動或繼續應用程式之間潛在的垃圾延遲。
codePush.InstallMode.ON_NEXT_RESTART (1) - 指出您想要安裝更新，但不會強制重新啟動應用程式。當應用程式「自然」重新啟動 (，因為操作系統或終端使用者) 終止，更新將會順暢地挑選。當執行無訊息更新時，這個值很適合，因為如果應用程式突然從任何地方重新啟動，對終端使用者可能會造成干擾。他們甚至不會發現已下載更新。這是用於 sync 和 LocalPackage.install 方法的預設模式。
codePush.InstallMode.ON_NEXT_RESUME (2) - 指出您想要安裝更新，但在下次使用者從背景繼續更新之前，不要重新啟動應用程式。如此一來，您就不會中斷其目前的會話，但您可以更快取得更新，而不是等待下一個自然重新啟動。此值適用於以非入侵方式在繼續時套用的無訊息安裝。
codePush.InstallMode.ON_NEXT_SUSPEND (3) - 指出您想要在背景中 安裝更新， 但只有在背景 (0) 幾秒鐘後 minimumBackgroundDuration ，才會遺失用戶內容，除非應用程式暫停夠長，才不重要。

CheckFrequency

此列舉會指定何時要讓應用程式與伺服器同步以進行更新，並可傳遞至 codePushify 裝飾專案。其中包含下列值：

codePush.CheckFrequency.ON_APP_START (0) - 指出您想要在應用程式進程啟動時檢查更新。
codePush.CheckFrequency.ON_APP_RESUME (1) - 指出每當應用程式在「背景」後回到前景時，您想要檢查更新， (使用者按下首頁按鈕、應用程式會啟動個別的付款程式，依此類推) 。
codePush.CheckFrequency.MANUAL (2) - 停用更新的自動檢查，但只有在應用程式程式代碼中呼叫時才 codePush.sync() 檢查。

SyncStatus

此列舉會提供給 syncStatusChangedCallback 可以傳遞至方法的 sync 函式，以攔截到整體更新程式。其中包含下列值：

codePush.SyncStatus.CHECKING_FOR_UPDATE (0) - 正在查詢 CodePush 伺服器以進行更新。
codePush.SyncStatus.AWAITING_USER_ACTION (1) - 有可用的更新，並向使用者顯示確認對話方塊。 (只有在使用) 時才 updateDialog 適用。
codePush.SyncStatus.DOWNLOADING_PACKAGE (2) - 正在從 CodePush 伺服器下載可用的更新。
codePush.SyncStatus.INSTALLING_UPDATE (3) - 已下載可用的更新，即將安裝。
codePush.SyncStatus.UP_TO_DATE (4) - 應用程式已設定的部署完全最新。
codePush.SyncStatus.UPDATE_IGNORED (5) - 應用程式具有選擇性更新，終端使用者選擇忽略。 (只有在使用) 時才 updateDialog 適用。
codePush.SyncStatus.UPDATE_INSTALLED (6) - 已安裝可用的更新，且會在函式傳回之後syncStatusChangedCallback立即執行，或下次應用程式繼續/重新啟動時，視中指定的 SyncOptions而定InstallMode。
codePush.SyncStatus.SYNC_IN_PROGRESS (7) - 有持續 sync 作業可防止執行目前的呼叫。
codePush.SyncStatus.UNKNOWN_ERROR (-1) - 同步作業發現未知的錯誤。

UpdateState

此列舉會指定更新目前所在的狀態，而且可以在呼叫 getUpdateMetadata 方法時指定。其中包含下列值：

codePush.UpdateState.RUNNING (0) - 指出更新代表目前正在執行的應用程式版本。這對於識別應用程式的相關屬性很有用，例如在「新功能？」對話框中顯示發行描述，或向分析或當機報告服務報告最新版本。
codePush.UpdateState.PENDING (1) - 指出已安裝更新，但尚未重新啟動應用程式以套用更新。這適用於判斷是否有擱置的更新，您可能想要透過套用) restartApp 強制程式設計重新啟動 (。
codePush.UpdateState.LATEST (2) - 指出更新代表最新的可用版本，而且可以是目前執行中或擱置中。

objective-C API 參考 (iOS)

Objective-C API 可藉由將 CodePush.h 標頭匯入至 AppDelegate.m 檔案，並包含名為 CodePush的單一公用類別。

CodePush

包含用來擷NSURL取代表最近 JavaScript 套件組合檔案之的靜態方法，而且可以在 AppDelegate.m 檔案中啟動應用程式時傳遞至 RCTRootView的 initWithBundleURL 方法。

類別 CodePush 的方法可以視為複合解析程式，這一律會載入適當的配套，以容納下列案例：

當使用者從市集安裝您的應用程式 (，例如 1.0.0) 時，他們會取得二進位檔中包含的 JS 套件組合。這是您在不使用 CodePush 的情況下取得的行為，但我們確定不會中斷：)
一旦您開始發行 CodePush 更新，您的終端使用者就會取得 JS 套件組合，代表所設定部署的最新版本。這是一種行為，可讓您逐一查看您運送到商店的內容。
一旦您發行應用程式市集的更新 (，例如 1.1.0) ，而且您的終端使用者會更新它，他們就會再次取得二進位檔中包含的 JS 套件組合。此行為可確保以舊版二進位版本為目標的CodePush更新不會使用 (，因為我們不知道它們會運作) ，而且您的終端使用者一律會有一個運作中的應用程式版本。
重複 #2 和 #3，因為 CodePush 版本和 App Store 版本會繼續進入無限大 (和更新版本？)

由於這種行為，您可以視需要安全地將更新部署到應用程式市集 () 和 CodePush，並放心地確保您的終端使用者一律會取得最新版本。

方法

(NSURL *) bundleURL - 傳回上述最新的 JS 套件組合 NSURL 。這個方法假設應用程式二進位檔中包含的 JS 套件組合名稱是 main.jsbundle。
(NSURL *) bundleURLForResource： (NSString *) resourceName - 相當於 bundleURL 方法，但也允許自定義在應用程式二進位檔內搜尋的 JS 套件組合名稱。如果您未命名此檔案 main ， (這是預設慣例) ，這會很有用。這個方法假設 JS 套件組合的延伸模組為 *.jsbundle。
(NSURL *) bundleURLForResource： (NSString *) resourceName withExtension： (NSString *) resourceExtension：相當於 bundleURLForResource: 方法，但也允許自定義在應用程式二進位檔內搜尋的 JS 套件組合所使用的擴充功能。如果您未命名此檔案 *.jsbundle ， (這是預設慣例) ，這會很有用。
(void) overrideAppVersion： (NSString *) appVersionOverride - 設定應用程式的二進位介面版本，否則會預設為 CFBundleShortVersionStringInfo.plist 中指定的 App Store 版本。這應該會在載入套件組合 URL 之前，先呼叫一次。
(void) setDeploymentKey： (NSString *) deploymentKey - 設定應用程式在查詢更新時應該使用的部署密鑰。這是在 Info.plist 中設定部署金鑰或在 JS 中指定部署密鑰的動態替代方式，是在呼叫 checkForUpdate 或 sync時指定部署金鑰。

Java API 參考 (Android)

React Native 0.60 版和更新版本的 API

由於 autolinking 會使用 react-native.config.js 連結外掛程式，因此會在該檔案中指定建構函式。但您可以將這些值放在字串資源中，以覆寫自定義變數來管理 CodePush 外掛程式。

公鑰 - 用於程式代碼簽署功能中的套件組合驗證。如需程式代碼簽署功能的詳細資訊，請參閱程式代碼簽署一節。若要設定公鑰，您應該使用名稱 CodePushPublicKey將公鑰的內容新增至 strings.xml 。 CodePush 會自動取得此屬性，並啟用程式代碼簽署功能。例如：
```
<string moduleConfig="true" name="CodePushPublicKey">your-public-key</string>
```
伺服器 URL - 用於指定 CodePush 伺服器 URL。默認值：“https://codepush.appcenter.ms/"透過使用名稱 CodePushServerUrl將路徑新增至 strings.xml ，以覆寫。 CodePush 會自動取得此屬性，並使用這個路徑來傳送要求。例如：
```
<string moduleConfig="true" name="CodePushServerUrl">https://yourcodepush.server.com</string>
```

React Native 低於0.60的 API

Java API 可藉由將 com.microsoft.codepush.react.CodePush 類別匯入 您的MainActivity.java 檔案，並包含名為 CodePush的單一公用類別。

CodePush

建構 CodePush 用戶端運行時間，並代表 ReactPackage 您新增至應用程式套件清單的實例。

建構函式

CodePush (String deploymentKey， Activity mainActivity) - 建立 CodePush 運行時間的新實例，用來透過提供的部署密鑰查詢服務是否有更新。在 mainActivity 類別內設定 React 套件清單時，應該一律將參數設定this為 MainActivity 。此建構函式會將 CodePush 運行時間放入「發行模式」，因此如果您想要啟用偵錯行為，請改用下列建構函式。
CodePush (String deploymentKey， Activity mainActivity， bool isDebugMode) - 相當於先前的建構函式，但可讓您指定是否要 CodePush 運行時間處於偵錯模式。使用此建構函式時， isDebugMode 應該一律將參數設定為 BuildConfig.DEBUG ，以與組建類型保持同步。將 CodePush 放入偵錯模式時，會啟用下列行為：
1. 每當新的二進位檔部署至模擬器/裝置時，不會從記憶體中刪除舊的CodePush更新。此行為可讓您部署新的二進位檔，而不需要在開發期間增加版本，而且不會在每次應用程式呼叫 sync時持續取得相同的更新。
2. 每當安裝 CodePush 更新時，就會刪除 React Native 執行時間在偵錯模式中維護的本機快取。這可確保在套用更新之後重新啟動應用程式時，可能會看到預期的變更。一旦合併此PR ，我們就不需要再執行此動作。
CodePush (String deploymentKey， Context context， boolean isDebugMode， Integer publicKeyResourceDescriptor) - 相當於先前的建構函式，但可讓您指定讀取公鑰內容所需的公鑰資源描述元。如需程式代碼簽署功能的詳細資訊，請參閱程式代碼簽署一節。
CodePush (String deploymentKey， Context context， boolean isDebugMode， String serverUrl) - 建構函式可讓您指定 CodePush 伺服器 URL。預設值： "https://codepush.appcenter.ms/" 是由中指定的 serverUrl值覆寫。

靜態方法

getBundleUrl () - 傳回應用程式 JS 套件組合檔案最新版本的路徑，假設資源名稱為 index.android.bundle。如果您的應用程式使用不同的套件組合名稱，請使用此方法的多載版本，以允許指定它。這個方法的解析行為與上述 Objective-C 對等專案相同。
getBundleUrl (String bundleName) - 使用指定的資源名稱 (，傳回應用程式 JS 套件組合檔案最新版本的路徑，例如 index.android.bundle) 。這個方法的解析行為與上述 Objective-C 對等專案相同。
overrideAppVersion (String appVersionOverride) - 設定應用程式的二進位介面版本，否則預設為 build.gradle 中指定的 Play 市集版本versionName。在建構 CodePush 實例之前，這應該先呼叫一次。

Share via

React Native 用戶端 SDK API 參考

JavaScript API 參考

codePush

CodePushOptions

codePushStatusDidChange (事件攔截)

codePushDownloadDidProgress (事件攔截)

codePush.allowRestart

codePush.checkForUpdate

codePush.disallowRestart

codePush.getCurrentPackage

codePush.getUpdateMetadata

codePush.notifyAppReady

codePush.restartApp

codePush.sync

SyncOptions

封裝物件

LocalPackage

屬性

方法

RemotePackage

屬性

方法

列舉

InstallMode

CheckFrequency

SyncStatus

UpdateState

objective-C API 參考 (iOS)

CodePush

方法

Java API 參考 (Android)

React Native 0.60 版和更新版本的 API

React Native 低於0.60的 API

CodePush

建構函式

靜態方法

意見反應

意見反應

其他資源