Cordova クライアント SDK

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

重要

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

サポートタイムラインと代替方法の詳細をご確認ください。

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

Note

Cordova アプリのサポートは 2022 年 4 月に終了しました。詳細については、 App Center ブログを参照してください。

それはどのように機能しますか?

Cordova アプリは、HTML、CSS、JavaScript ファイルとそれに付随するイメージで構成されています。これは Cordova CLI によってバンドルされ、プラットフォーム固有のバイナリ (.ipa または .apk ファイル) の一部として配布されます。アプリがリリースされたら、コード資産またはイメージ資産を更新するには、バイナリ全体を再コンパイルして再配布する必要があります。このプロセスには、発行するストアのレビュー時間が含まれます。

CodePush プラグインは、CodePush サーバーにリリースした更新プログラムとコードとイメージの同期を維持することで、エンドユーザーの前で製品の改善を即座に実現するのに役立ちます。これにより、アプリはオフラインモバイルエクスペリエンスの利点と、更新プログラムが利用可能になるとすぐにサイドローディングの "Web に似た" 機敏性を得られます。両方にプラスになるのです。

エンドユーザーが常に機能しているバージョンのアプリを持っていることを確認するために、CodePush プラグインは以前の更新プログラムのコピーを保持するため、クラッシュを含む更新プログラムを誤ってプッシュした場合は、自動的にロールバックできます。これにより、新しいリリースの機敏性によって、サーバーにロールバックする前にユーザーがブロックされることはありません。これは win-win-win です。

Note

ネイティブコードに触れる製品の変更 (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 アカウントを設定するための汎用 "getting started" の手順に従ったら、アプリのルートディレクトリ内から次のコマンドを実行して、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-Policy meta タグに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();
});

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

重要

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

更新プログラムのリリース

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

Note

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

最も基本的な形式では、このコマンドには、所有者名 + "/" + アプリ名の 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 ランタイムに通知します。更新プログラムを手動で確認してインストールする場合 (つまり、同期メソッドを使用してすべてを処理しない場合)、このメソッド MUST が呼び出されます。それ以外の場合、CodePush は更新プログラムを失敗として処理し、アプリの次回再起動時に以前のバージョンにロールバックします。
restartApplication: アプリを直ちに再起動します。保留中の更新がある場合は、すぐにエンドユーザーに表示されます。
sync: 更新プログラムの確認、ダウンロード、インストールを 1 回の呼び出しで行うことができます。カスタム UI または動作が必要な場合を除き、ほとんどの開発者は CodePush をアプリに統合するときにこのメソッドを使用することをお勧めします。

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

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

codePush.checkForUpdate

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

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

更新チェックが完了すると、次の 2 つの値のいずれかを使用して onUpdateCheck コールバックがトリガーされます。

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

現在インストールされている "パッケージ" に関するメタデータ (説明、インストール時間など) を取得します。これは、更新プログラムが適用された後に "新着情報" ダイアログを表示したり、再開または再起動によって適用されるのを待っている保留中の更新があるかどうかを確認したりするシナリオに役立ちます。

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

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

パラメーター:

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

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

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

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

パラメーター:

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

パラメーター:

notifySucceeded: プラグインが正常に通知された場合に呼び出される省略可能なコールバック。
notifyFailed: プラグインに通知するエラーが発生した場合に呼び出される省略可能なコールバック。

codePush.restartApplication

codePush.restartApplication();

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

syncまたはLocalPackage.installメソッドを呼び出すときに、アプリでインストールモードの値が ON_NEXT_RESTART またはON_NEXT_RESUME指定されています。これは、アプリが (エンドユーザーまたは 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 スレッドの応答性には影響しません。

パッケージオブジェクト

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

LocalPackage: ダウンロードした更新プログラムを表します。既に実行されているか、インストールされていて、アプリの再起動が保留中です。
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と同じプロパティをすべて継承しますが、さらに 1 つのプロパティが含まれます。

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

メソッド

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 には、更新エクスペリエンスをカスタマイズするために使用できる次の "列挙型" オブジェクトが含まれており、 window オブジェクトからグローバルに使用できます。

InstallMode

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

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

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

RemotePackage

プロパティ

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

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

メソッド

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

列挙型

InstallMode

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

SyncStatus

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

UP_TO_DATE: アプリは、構成されたデプロイで完全に最新です。
UPDATE_INSTALLED: 使用可能な更新プログラムがインストールされ、SyncOptionsで指定されたInstallModeに応じて、コールバック関数が戻った直後または次回アプリが再開/再起動したときに実行されます。
UPDATE_IGNORED: アプリにオプションの更新プログラムがあり、エンドユーザーが無視するように選択しました。 (これは、 updateDialog が使用されている場合にのみ適用されます)
ERROR: 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 を使用します)。これを解決するには、<platform name="android">要素の子として、次の要素をプロジェクトのconfig.xml ファイルに追加します。

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

アプリの例

Cordova コミュニティは、作業を開始する開発者の例として役立つ素晴らしいオープンソースアプリをいくつか優れた方法で作成しました。次の一覧は、CodePush も使用している OSS Cordova アプリの一覧であり、他のユーザーがサービスをどのように使用しているかを確認するために使用できます。

PGDay CodePush Demo - PhoneGap Day Europe 2016 で使用 Rangle.io によって作成されたデモアプリ。

Note

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

アプリの例

フィードバック

その他のリソース

パッケージオブジェクト