Cordova クライアント SDK

[アーティクル]
07/19/2023

重要

Visual Studio App Center は、2025 年 3 月 31 日に廃止される予定です。完全に廃止されるまで Visual Studio App Center を引き続き使用できますが、移行を検討できる推奨される代替手段がいくつかあります。

詳細については、サポートタイムラインと代替手段に関するページを参照してください。

このプラグインは、CodePush サービスのクライアント側統合を提供し、Cordova アプリに動的な更新エクスペリエンスを簡単に追加できます。

注意

Cordova アプリのサポートは 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 以降) - (プラグインと共 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

作業の開始

Note

この記事には、Microsoft が使用しなくなった "ホワイトリスト" という用語への言及があります。この用語は、ソフトウェアから削除された時点でこの記事から削除されます。

CodePush アカウントを設定するための汎用の "はじめに" の手順に従ったら、アプリのルートディレクトリ内から次のコマンドを実行して、Cordova アプリの CodePush 化を開始できます。

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し、使用する特定のデプロイのキーを取得できます (例: Staging、 Production)。

重要

iOS と Android 用の個別の CodePush アプリを作成することをお勧めします。そのため、上記のサンプルでは Android と iOS 用に個別のキーが宣言されています。 1 つのプラットフォームでのみ開発している場合は、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 サーバーに確実にアクセスできるようにするには、ファイルの index.html タグにをContent-Security-Policymeta追加https://codepush.appcenter.msします。

    <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();

更新プログラムが利用可能な場合は、サイレントモードでダウンロードされ、次回アプリが再起動されるときに (エンドユーザーまたは OS によって明示的に) インストールされます。これにより、エンドユーザーのエクスペリエンスが最も低くなります。利用可能な更新プログラムが必須の場合は、すぐにインストールされ、エンドユーザーができるだけ早く入手できるようになります。

アプリで更新プログラムをより迅速に検出する場合は、アプリの起動動作の一部として次のコード (または同等のもの) を追加することで、アプリがバックグラウンドから再開されるたびにを呼び出 sync すこともできます。必要な頻度で呼び出すことができます。そのため、呼び出 sync すタイミングと場所は、個人の好みによって異なります。

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

さらに、更新の確認ダイアログ ("アクティブなインストール") を表示する場合は、利用可能な更新プログラムがインストールされたときにを構成するか (即時再起動を強制するなど)、更新エクスペリエンスを何らかの方法でカスタマイズする場合は、この既定の動作を調整する方法については、メソッドの API リファレンスを参照してください sync 。

重要

Apple の開発者契約では、JavaScript と資産 (CodePush を有効にする機能) のオンエア更新が完全に許可されていますが、アプリが更新プロンプトを表示するのはポリシーに反します。このため、App Store分散アプリでは、を呼び出syncすときにオプションを有効updateDialogにしないことをお勧めします。一方、Google Play と内部分散アプリ (Enterprise、Fabric、HockeyApp など) では有効/カスタマイズを選択できます。

更新のリリース

アプリが構成され、ユーザーに配布され、コードまたは資産の変更が完了したら、すぐに解放します。これを行う最も簡単な (推奨される) 方法は、CodePush CLI でコマンドを使用 release-cordova することです。これにより、CodePush サーバーへの更新の準備とリリースが処理されます。

注意

更新プログラムのリリースを開始する前に、コマンドを実行して App Center に appcenter login ログインします

最も基本的な形式では、このコマンドに必要なパラメーターは、所有者名 + "/" + アプリ名の 1 つだけです。

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参照してください。

問題が発生した場合、または質問/コメント/フィードバックがある場合は、電子メールを送信するか、このリポジトリで新しい問題を開くと、できるだけ早く応答します。ヘルプとフィードバックも参照してください。

API リファレンス

CodePush API は、イベントの発生後に使用できるグローバル codePush オブジェクトを介してアプリに deviceready 公開されます。この API は、次の最上位のメソッドを公開します。

checkForUpdate: 構成されたアプリのデプロイに更新プログラムがあるかどうかを CodePush サービスに確認します。
getCurrentPackage: 現在インストールされている更新プログラムに関するメタデータ (説明、インストール時間、サイズなど) を取得します。
getPendingPackage: ダウンロードおよびインストールされた更新プログラム (存在する場合) のメタデータを取得しますが、再起動によってまだ適用されていません。
notifyApplicationReady: インストールされている更新プログラムが成功したと見なされることを CodePush ランタイムに通知します。更新プログラムを手動で確認してインストールする場合 (つまり、sync メソッドを使用してすべてを処理しない場合)、このメソッドを呼び出す 必要があります 。それ以外の場合、CodePush は更新プログラムを失敗として扱い、アプリの次回の再起動時に以前のバージョンにロールバックします。
restartApplication: アプリを直ちに再起動します。保留中の更新がある場合は、すぐにエンドユーザーに表示されます。
sync: 更新プログラムの確認、ダウンロード、インストールを 1 回の呼び出しで行うことができます。カスタム UI または動作が必要な場合を除き、ほとんどの開発者は CodePush をアプリに統合するときにこのメソッドを使用することをお勧めします。

さらに、次のオブジェクトと列挙型も CodePush API の一部としてグローバルに公開されます。

InstallMode: 更新プログラムに使用できるインストールモードを定義します。
LocalPackage: ローカルにインストールされたパッケージに関する情報が含まれています。
RemotePackage: ダウンロード可能な更新プログラムパッケージに関する情報が含まれています。
SyncStatus: 同期操作の中間および結果の状態を定義します。

codePush.checkForUpdate

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

CodePush サービスに対してクエリを実行して、構成されたアプリのデプロイに更新プログラムが利用可能かどうかを確認します。既定では、 config.xml ファイルで構成されているデプロイキーが使用されますが、省略可能 deploymentKey なパラメーターを使用して値を指定することでオーバーライドできます。これは、イースターエッグやユーザー設定スイッチを介して "早期アクセス" を許可するなど、ユーザーを特定のデプロイに動的に "リダイレクト" する場合に便利です。

更新チェックが完了すると、次の onUpdateCheck 2 つの可能な値のいずれかでコールバックがトリガーされます。

null 利用可能な更新プログラムがない場合は。これは、次のシナリオで発生します。
- 構成されたデプロイにはリリースが含まれていないため、更新する必要はありません。
- 構成されたデプロイ内の最新リリースでは、現在実行されているもの (古いバージョンまたは新しいバージョン) とは異なるバイナリバージョンがターゲットになっています。
- 現在実行中のアプリには、構成されたデプロイからの最新のリリースが既に存在するため、もう一度リリースは必要ありません。
RemotePackage検査して後でダウンロードできる利用可能な更新プログラムを表すインスタンス。

パラメーター:

onSuccess: サーバーからの正常な応答を受信したときに呼び出されるコールバック。コールバックは、上記で説明した 1 つのパラメーターを受け取ります。
onError: エラーが発生した場合に呼び出されるオプションのコールバック。コールバックは、エラーの詳細を含む 1 つのエラーパラメーターを受け取ります。
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 2 つの可能な値のいずれかを使用してコールバックがトリガーされます。

null アプリが現在 CodePush 更新ではなくバイナリから HTML スタートページを実行している場合。これは、次のシナリオで発生します。
- エンドユーザーがアプリバイナリをインストールし、CodePush 更新プログラムをまだインストールしていない
- エンドユーザーはバイナリの更新プログラム (ストアからなど) をインストールしました。これにより、古い CodePush 更新プログラムがクリアされ、優先順位がバイナリに戻されました。
LocalPackage現在実行中の CodePush 更新プログラムのメタデータを表すインスタンス。

パラメーター:

onSuccess: 現在実行中の更新に関するメタデータを受信したときに呼び出されるコールバック。コールバックは、上記で説明した 1 つのパラメーターを受け取ります。
onError: エラーが発生した場合に呼び出されるオプションのコールバック。コールバックは、エラーの詳細を含む 1 つのエラーパラメーターを受け取ります。

使用例:

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?);

現在保留中の更新プログラムのメタデータを取得します (存在する場合)。更新プログラムがダウンロードされてインストールされているが、アプリの再起動によってまだ適用されていない場合、更新プログラムは "保留中" と見なされます。またはの呼び出しLocalPackage.installsync時にまたはが指定され、アプリがまだ再起動または再開されていない場合InstallMode.ON_NEXT_RESTARTInstallMode.ON_NEXT_RESUMEにのみ、更新プログラムがこの状態になる可能性があります (それぞれ)。このメソッドは、保留中の更新があるかどうかを判断し、(経由で codePush.restartApplication) すぐに再起動して適用するかどうかをユーザーに求める場合に便利です。

更新プログラムの取得が完了すると、次の onSuccess 2 つの可能な値のいずれかを使用してコールバックがトリガーされます。

null アプリに現在保留中の更新がない場合 (たとえば、アプリで使用可能な最新バージョンが既に実行されています)。
LocalPackage現在保留中の CodePush 更新プログラムのメタデータを表すインスタンス。

パラメーター:

onSuccess: 現在保留中の更新に関するメタデータの受信時に呼び出されるコールバック。コールバックは、上記で説明した 1 つのパラメーターを受け取ります。
onError: エラーが発生した場合に呼び出されるオプションのコールバック。コールバックは、エラーの詳細を含む 1 つのエラーパラメーターを受け取ります。

使用例:

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使用していて、アプリの起動時に更新チェックを実行している場合は、手動でを呼び出すnotifyApplicationReadysync必要はありません。この動作は、アプリでが sync 呼び出されると、正常なスタートアップの適切な近似を表すという前提があるために存在します。

パラメーター:

notifySucceeded: プラグインが正常に通知された場合に呼び出されるオプションのコールバック。
notifyFailed: プラグインを通知するエラーが発生した場合に呼び出されるオプションのコールバック。

codePush.restartApplication

codePush.restartApplication();

アプリを直ちに再起動します。この方法は高度なシナリオ用であり、主に次の条件に該当する場合に役立ちます。

アプリで、メソッドまたはメソッドを呼び出すときに、または ON_NEXT_RESUME のON_NEXT_RESTARTインストールモードの値をsyncLocalPackage.install指定しています。これは、アプリが再起動 (エンドユーザーまたは OS) または再開するまで更新プログラムを適用しないため、更新プログラムはすぐにエンドユーザーに表示されません。
アプリ固有のユーザーイベント (エンドユーザーがアプリのホームルートに戻ったなど) があり、これにより、目立たない方法で更新プログラムを適用でき、次の再起動または再開まで待つよりも早くエンドユーザーの前で更新プログラムを取得する可能性があります。

codePush.sync

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

アプリのコードとイメージを、構成されたデプロイに対する最新リリースと同期します。更新プログラムのcheckForUpdate存在を確認し、次に何を行うかを制御できるメソッドとは異なり、sync更新プログラムのチェック、ダウンロード、インストールエクスペリエンスを処理します。

この方法では、次の 2 つの異なる (ただしカスタマイズ可能な) "モード" がサポートされ、さまざまな要件を持つアプリを簡単に有効にすることができます。

サイレントモード(既定の動作)。利用可能な更新プログラムが自動的にダウンロードされ、次回アプリが再起動されたとき (OS またはエンドユーザーが強制終了した、デバイスが再起動されたなど) に適用されます。これにより、更新プロンプトや "合成" アプリの再起動が表示されないため、更新エクスペリエンス全体がエンドユーザーに対して "サイレント" になります。
更新プログラムが利用可能な場合、アクティブモードでは、エンドユーザーにアクセス許可を求めてからダウンロードし、直ちに更新プログラムを適用します。必須フラグを使用して更新プログラムがリリースされた場合でも、エンドユーザーには更新プログラムに関する通知が表示されますが、無視する選択肢はありません。

使用例:

// 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: 同期プロセスが更新プロセス全体で 1 つのステージから別のステージに移動したときに呼び出されます。メソッドは、現在の状態を表す状態コードを使用して呼び出され、任意の値を SyncStatus 指定できます。
syncOptions: 同期操作の動作を構成する省略可能な SyncOptions パラメーター。
downloadProgress: 利用可能な更新プログラムが CodePush サーバーからダウンロードされるときに定期的に呼び出されます。メソッドは、次の 2 つのプロパティを DownloadProgress 含むオブジェクトを使用して呼び出されます。
- totalBytes(Number) - この更新プログラムで受信される予定の合計バイト数 (つまり、以前のリリースから変更されたファイルのセットのサイズ)。
- receivedBytes(Number) - これまでにダウンロードしたバイト数。ダウンロードの進行状況を追跡するために使用できます。
syncErrback: 同期内部ステップのいずれかでエラーが発生したときに呼び出されます。メソッドは、標準の javascript Error オブジェクトを最初の引数として使用して呼び出されます。

SyncOptions

syncこのメソッドは、構成がほとんどない状態でサイレント更新とアクティブ更新を簡単に行えるように試みますが、上記の既定の動作のさまざまな側面をカスタマイズできる "options" オブジェクトを受け入れます。

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(Boolean) - 使用可能な更新プログラムが以前にインストールされ、クライアントにロールバックされた場合に無視するかどうかを指定します (正常に呼び出されなかったためです notifyApplicationReady )。既定値は true です。
updateDialog(UpdateDialogOptions) - 更新プログラムが利用可能な場合に、確認ダイアログをエンドユーザーに表示する必要があるかどうかを判断するために使用される "options" オブジェクトと、使用する文字列。既定値はに null設定され、ダイアログが無効になります。これを任意 true の値に設定すると、既定の文字列を含むダイアログが有効になり、オブジェクトをこのパラメーターに渡すと、ダイアログを有効にしたり、既定の文字列の 1 つ以上をオーバーライドしたりできます。

次の一覧は、使用可能なオプションとその既定値を表しています。

appendReleaseDescription(Boolean) - エンドユーザーに表示される通知メッセージに、使用可能なリリースの説明を追加するかどうかを示します。既定値は 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 スレッドの応答性には影響しません。

パッケージオブジェクト

メソッドと getCurrentPackage メソッドはcheckForUpdate成功コールバックを呼び出します。このコールバックはトリガーされると、"package" オブジェクトへのアクセスを提供します。パッケージは、コードの更新と、追加のメタデータ (説明、必須など) を表します。 CodePush API には、次の種類のパッケージが区別されています。

LocalPackage: ダウンロードした更新プログラムを表します。既に実行されているか、インストールされていて、アプリの再起動が保留中です。
RemotePackage: まだダウンロードされていない CodePush サーバーで使用可能な更新プログラムを表します。

LocalPackage

ローカルまたは既にインストールされている更新プログラムに関する詳細が含まれます。メソッドを呼び出 codePush.getCurrentPackage すか、メソッドの成功コールバックに指定された値として、このオブジェクトのインスタンスへの参照を RemotePackage.download 取得できます。

プロパティ

appVersion: このパッケージ更新プログラムの対象となるアプリケーションのネイティブバージョン。 (String)
deploymentKey: パッケージのデプロイキー。 (String)
description: 更新プログラムの説明。これは、更新プログラムをリリースしたときに CLI で指定した値と同じです。 (String)
failedInstall: この更新プログラムが以前にインストールされていてもロールバックされたかどうかを示します。メソッドは sync 、以前に失敗した更新プログラムを自動的に無視するため、を使用 checkForUpdateしている場合にのみ、このプロパティについて心配する必要があります。 (Boolean)
isFirstRun: 現在のアプリケーション実行がパッケージの適用後の最初の実行であるかどうかを示すフラグ。 (Boolean)
isMandatory: 更新が必須と見なされるかどうかを示します。これは、更新プログラムがリリースされたときに CLI で指定された値です。 (Boolean)
label: CodePush サーバーによって更新に自動的に与えられる内部ラベル (例: v5)。この値は、展開内の更新プログラムを一意に識別します。 (String)
packageHash: 更新プログラムの SHA ハッシュ値。 (String)
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さらに 1 つのプロパティが含まれます。

downloadUrl: パッケージをダウンロードできる URL。メソッドは自動的に更新プログラムの取得を download 処理するため、このプロパティは高度な使用にのみ必要です。 (String)

メソッド

abortDownload(abortSuccess, abortError): 現在のダウンロードセッションがある場合は中止します。
download(downloadSuccess, downloadError, downloadProgress): CodePush サービスからパッケージ更新プログラムをダウンロードします。コールバックは downloadSuccess 、ダウンロードしたパッケージを表す LocalPackage 引数を使用して呼び出されます。オプション downloadProgress のコールバックは、ダウンロードの進行状況中に 1 つの 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 には、更新エクスペリエンスのカスタマイズに使用できる次の "enum" オブジェクトが含まれており、オブジェクトから window グローバルに使用できます。

InstallMode

この列挙型は、インストールされている更新プログラムを実際に適用する場合に指定し、メソッドまたは LocalPackage.install メソッドのいずれかにsync渡すことができます。これには、次の値が含まれます。

IMMEDIATE: 更新プログラムは、実行中のアプリケーションにすぐに適用されます。アプリケーションは、新しいコンテンツですぐに再読み込みされます。
ON_NEXT_RESTART: 更新プログラムをインストールするが、アプリを強制的に再起動しないことを示します。アプリが "自然に" 再起動されると (OS またはエンドユーザーがアプリを強制終了したため)、更新プログラムがシームレスに取得されます。この値は、サイレント更新を実行する場合に適しています。これは、アプリが突然どこからともなく再起動した場合にエンドユーザーに混乱を与える可能性があるため、更新プログラムがダウンロードされたことも認識していないためです。これは、メソッドと LocalPackage.install メソッドの両方で使用される既定のsyncモードです。

不適切な更新から保護される方法の例については、 notifyApplicationReady() のドキュメントを参照してください。

RemotePackage

CodePush サーバーからダウンロードできる更新プログラムの詳細が含まれています。このオブジェクトのインスタンスへの参照を取得するには、更新プログラムが利用可能になったときにメソッドを codePush.checkForUpdate 呼び出します。同期 API を使用している場合は、ダウンロードとインストールのプロセスが自動的に処理されるため、について RemotePackage心配する必要はありません。

プロパティ

は RemotePackage と同じプロパティをすべて継承しますが、 LocalPackage追加のプロパティが 1 つ含まれています。

downloadUrl: パッケージをダウンロードできる URL。メソッドは自動的に更新プログラムの取得を download 処理するため、このプロパティは高度な使用にのみ必要です。 (String)

メソッド

abortDownload(abortSuccess, abortError): 現在のダウンロードセッションがある場合は中止します。
download(downloadSuccess, downloadError, downloadProgress): CodePush サービスからパッケージの更新プログラムをダウンロードします。コールバックは downloadSuccess 、ダウンロードしたパッケージを表す LocalPackage 引数を使用して呼び出されます。オプション downloadProgress のコールバックは、ダウンロードの進行状況中に 1 つの 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 には、更新エクスペリエンスをカスタマイズするために使用できる次の "enum" オブジェクトが含まれており、オブジェクトから window グローバルに使用できます。

InstallMode

IMMEDIATE: 更新プログラムは、実行中のアプリケーションにすぐに適用されます。アプリケーションは、新しいコンテンツですぐに再読み込みされます。
ON_NEXT_RESTART: 更新プログラムをインストールするが、アプリを強制的に再起動しないことを示します。アプリが "自然に" 再起動されると (OS またはエンドユーザーがアプリを強制終了したため)、更新プログラムがシームレスに取得されます。この値は、サイレント更新を実行する場合に適しています。これは、アプリが突然どこからともなく再起動した場合にエンドユーザーに混乱を与える可能性があるため、更新プログラムがダウンロードされたことも認識していないためです。これは、メソッドと LocalPackage.install メソッドの両方で使用される既定のsyncモードです。
ON_NEXT_RESUME: 更新プログラムをインストールするが、次回エンドユーザーがバックグラウンドから再開するまでアプリを再起動しないことを示します。この方法では、現在のセッションを中断することはありませんが、次の自然な再起動を待つよりも早く、その前に更新プログラムを取得できます。この値は、非侵襲的な方法で再開時に適用できるサイレントインストールに適しています。

SyncStatus

同期操作の可能な状態を定義します。状態には、中間と結果 (最終) の 2 つのカテゴリがあります。中間状態は同期操作の進行状況を表し、最終的な状態ではありません。結果の状態は、同期操作の最終的な状態を表します。すべての同期操作は結果の状態が 1 つだけで終了しますが、0 個以上の中間状態を持つことができます。

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 ビルドと互換性があり、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 デモ - PhoneGap Day Europe 2016 で使用 Rangle.io によって作成されたデモアプリ。

注意

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 ビルド

サンプルアプリ

その他のリソース

次の方法で共有

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 ビルド

サンプル アプリ

その他のリソース

パッケージオブジェクト

サンプルアプリ