In-App アップデーター プラグイン

アプリの再ビルド・再パッケージ化を行わずに、アプリで使用している HTML5 アセットを更新するためのプラグイン ( Monaca In-App Updater ) です。なお、更新ファイルをホストする Web サーバーが、別途、必要になります ( アプリから、これらのファイルへアクセスできること )。

このプラグインを使用するためには、対応するプランへの加入が必要となります。詳細は、 料金プラン をご確認ください。

サポート対象のプラットフォーム

  • Cordova 6.2 以降
  • iOS 8 以上
  • Android 4 以降

プラグインの追加方法

  1. Monaca クラウド IDE から 設定 → Cordova プラグインの管理 を選択します。

  2. 利用可能なプラグイン 項目の InAppUpdater プラグインにカーソルを置き、有効 ボタンをクリックします。

  3. 次に、有効なプラグイン 項目へ行き、先ほど追加したプラグイン上に、カーソルを置き、設定 ボタンをクリックします。

  4. CheckUpdate URLDownload URL 欄を適宜入力して、 OK ボタンをクリックします。

使い方

プラグインの設定

本プラグインを利用するためには、CheckUpdate URLDownload URL の二つのWeb API(URL)が必要となります。

CheckUpdate URL

サーバーにある更新バージョンを確認します

Request パラメーター

パラメーター 解説
project_id 文字列 プロジェクトの一意の ID
my_update_number 文字列 [ 任意 ] アプリの現在の更新番号
os 文字列 [ 任意 ] 更新対象となる OS の種類
build_type 文字列 [ 任意 ] ビルドの種類
app_version 文字列 [ 任意 ] アプリのバージョン
plugin_version 文字列 [ 任意 ] InAppUpdater プラグインのバージョン

Response パラメーター

成功時のレスポンス例

{
  "ios": {
    "2.1.0": { // app version
      "1": { // update number
        "date": 20170113,
        "url": "https://hogehoge.com/app/ios-v2.1.0.zip" // This parameter is optional.
      }
    }
  }
}

静的ファイルを使用する場合、すべてのバージョンを次のように列挙しておきます。

{
  "ios": {
    "2.1.0": { // app version
      "1": { // update number
        "date": 20170113,
        "url": "https://hogehoge.com/app/1/ios-v2.1.0.zip" //  This parameter is optional.
      },
      "2": { // update number
        "date": 20170113,
        "url": "https://hogehoge.com/app/2/ios-v2.1.0.zip" //  This parameter is optional.
      }
    },
    "2.2.0": { // app version
      "1": { // update number
        "date": 20170210,
        "url": "https://hogehoge.com/app/1/ios-v2.2.0.zip" //  This parameter is optional.
      }
    }
  }
}

上の例に示すように、更新番号の値は「日付」「URL」などの更新情報で構成されるJSONオブジェクトです。これは、 getServerVersion() メソッドの Promise によって返される JSON オブジェクトの updateInfo パラメータによって取得できます。

Download URL

更新用のパッケージファイル ( ZIP 形式 ) をダウンロードします。

download() メソッドでダウンロード URL を設定すると、この設定を省略できます。

Request パラメーター

パラメーター 解説
update_number 文字列 ダウンロードするバージョンの番号 ( 更新バージョン番号 )
project_id 文字列 プロジェクトの一意の ID
my_update_number 文字列 [ 任意 ] アプリの現在の更新番号
os 文字列 [ 任意 ] 更新対象となる OS の種類
build_type 文字列 [ 任意 ] ビルドの種類
app_version 文字列 [ 任意 ] アプリのバージョン
plugin_version 文字列 [ 任意 ] InAppUpdater プラグインのバージョン

Response パラメーター

成功時のレスポンスには、処理結果 ( Zip 形式 ) が入っています。

API リファレンス

このプラグインの最もシンプルな使用方法は、autoUpdate() を使用して、更新ファイルのダウンロード ( プラグインの設定 を参照のこと ) とアプリの更新を自動で行うことです。

getServerVersion()download()updateAndRestart() などのメソッドを組わせて使用すれば、更新処理をカスタマイズすることもできます。

このプラグインが提供しているメソッドは次のとおりです。

メソッド 解説
getServerVersion() 更新ファイルの情報をサーバー側から取得します。
forceStopGetServerVersion() getServerVersion() の処理を中断します。
getLocalVersion() 現在のアプリの更新番号を確認します。
download() 更新用ファイルをダウンロードします。
forceStopDownload() download() の処理を中断します。
updateAndRestart() ダウンロードした更新用ファイルを展開し、アプリを再起動します。
status() プラグインの状態を確認します。
showAlertDialog() ダイアログ ( タイトルとメッセージ ) を表示します。
dismissAlertDialog() 警告 ( Alert ) ダイアログを閉じます。
showProgressDialog() 進捗表示 ( Progress ) 用ダイアログを表示します。
changeProgressDialog() 進捗表示 ( Progress ) 用ダイアログを更新します。
dismissProgressDialog() 進捗表示 ( Progress ) 用ダイアログを閉じます。
networkStatus() ネットワークの状態 ( Wifi、3G/LTE、接続なし など ) を確認します。
terminateApp() アプリを強制終了します。
autoUpdate() 更新ファイルのダウンロードとアプリの更新を自動的に行います。

getServerVersion()

更新ファイルの情報をサーバー側から取得します。

monaca.InAppUpdater.getServerVersion([args: JSON object]): Promise

パラメーター ( JSON オブジェクト)

プロパティ 解説
connectDelay 数値 サーバー接続を開始するまでの待機時間 ( ミリ秒単位 )
connectTimeout 数値 ( Android 専用 ) サーバー接続時に適用するタイムアウト時間 ( ミリ秒単位 )
readTimeout 数値 ( Android 専用 ) サーバーからのレスポンス受信時に適用するタイムアウト時間 ( すべてのレスポンスを受け取るまでの時間、ミリ秒単位 )
timeoutForRequest 数値 ( iOS 専用 ) サーバーへのリクエスト送信時に適用するタイムアウト時間。タイムアウトが発生した場合でも、リクエストは自動的に再送信されます。エラーは出力されません。
timeoutForResponse 数値 ( iOS 専用 ) サーバーからのレスポンス受信時に適用するタイムアウト時間 ( すべてのレスポンスを受け取るまでの時間、ミリ秒単位 )

戻り値 (Promise)

  • 成功時のコールバックには、次のような内容の JSON オブジェクトが渡されます。

    プロパティ 解説
    needsUpdate 真偽値 アプリのバージョンを更新する必要があるかを示します。
    updatable 真偽値 更新用のファイルがサーバー側に置かれているかを示します。
    latestVersion 文字列 アプリの最新バージョン
    myVersion 文字列 現在のアプリバージョン
    latestUpdateNumber 文字列 現在のアプリバージョンに適用できる最新の更新番号
    myUpdateNumber 文字列 現在のアプリバージョンが使用している更新番号
    updateInfo JSON オブジェクト サーバー側の設定が、次のようになっている場合、
    {
      "ios": {
        "2.1.0": { // app version
          "1": { // update number
            "date": 20170113,
            "url": "https://hogehoge.com/app/ios-v2.1.0.zip" // This parameter is optional.
          }
        }
      }
    }
    
    updateInfo は、以下の内容となります。
    updateInfo = {
      "date": 20170113,
      "url": "https://hogehoge.com/app/ios-v2.1.0.zip"
    }
    
  • 失敗時のコールバックには、エラーを示す JSON オブジェクトが渡されます。

monaca.InAppUpdater.getServerVersion().then(
    function(json) {
        alert( JSON.stringify(json) );
        targetVersion = json.myVersion;
        targetUpdateNumber = json.latestUpdateNumber;
        url = json.updateInfo.url;
        alert( targetVersion );
        alert( targetUpdateNumber );
        alert( url );
    } ,
    function(fail) { alert( JSON.stringify(fail) ); }
);

forceStopGetServerVersion()

getServerVersion() の処理を中断します。

monaca.InAppUpdater.forceStopGetServerVersion(): Promise

パラメーター

  • なし

戻り値 (Promise)

  • 成功時のコールバックには、結果を格納した JSON オブジェクトが渡されます。
  • 失敗時のコールバックには、エラーを示す JSON オブジェクトが渡されます。

monaca.InAppUpdater.forceStopGetServerVersion().then(
    function(str) { alert("stop success"); } ,
    function(fail) { alert( JSON.stringify(fail) ); }
);

getLocalVersion()

現在のアプリの更新番号を確認します。

monaca.InAppUpdater.getLocalVersion(): Promise

パラメーター

  • なし

戻り値 (Promise)

  • 成功時のコールバックには、結果を格納した JSON オブジェクトが渡されます。
  • 失敗時のコールバックには、エラーを示す JSON オブジェクトが渡されます。

monaca.InAppUpdater.getLocalVersion().then(
    function(json) { alert( JSON.stringify(json) ); } ,
    function(fail) { alert( JSON.stringify(fail) ); }
);

download()

更新用ファイルをダウンロードします。

monaca.InAppUpdater.download(args: JSON object): Promise

パラメーター ( JSON オブジェクト)

プロパティ 解説
version 数値 対象のアプリバージョン
updateNumber 数値 更新番号
bufferSize 数値 ( Android 専用 ) バッファーサイズ ( バイト単位 )。デフォルト値は 8192 です。
url 文字列 設定された URL から Zip ファイルをダウンロードします。この値を設定しない場合には、Download URL の値 ( config.xml 内の monaca:updater_DownloadUrl ) が代わりに使用されます。
connectDelay 数値 サーバー接続を開始するまでの待機時間 ( ミリ秒単位 )
connectTimeout 数値 ( Android 専用 ) サーバー接続時に適用するタイムアウト時間 ( ミリ秒単位 )
readTimeout 数値 ( Android 専用 ) サーバーからのレスポンス受信時に適用するタイムアウト時間 ( すべてのレスポンスを受け取るまでの時間、ミリ秒単位 )
timeoutForRequest 数値 ( iOS 専用 ) サーバーへのリクエスト送信時に適用するタイムアウト時間。タイムアウトが発生した場合でも、リクエストは自動的に再送信されます。エラーは出力されません。
timeoutForResponse 数値 ( iOS 専用 ) サーバーからのレスポンス受信時に適用するタイムアウト時間 ( すべてのレスポンスを受け取るまでの時間、ミリ秒単位 )

戻り値 (Promise)

  • 成功時のコールバックには、結果を格納した JSON オブジェクトが渡されます。

  • 失敗時のコールバックには、エラーを示す JSON オブジェクトが渡されます。

  • 進捗表示コールバックには、ダウンロードの進捗状況を示す、次のような JSON オブジェクトが渡されます。

    名前 解説
    count 数値 これまでにダウンロードされたファイルのサイズ
    total 数値 ダウンロードされるファイルの予想サイズ

monaca.InAppUpdater.download( { version : targetVersion, updateNumber : targetBuildNumber, url : url } ).then(
    function(json) { alert( JSON.stringify(json) ); } ,
    function(fail) { alert( JSON.stringify(fail) ); } ,
    function(json) { console.log( json.count + "/" + json.total + " are done." ); }
);

forceStopDownload()

download() の処理を中断します。

monaca.InAppUpdater.forceStopDownload(): Promise

パラメーター

  • なし

戻り値 (Promise)

  • 成功時のコールバックには、結果を格納した JSON オブジェクトが渡されます。
  • 失敗時のコールバックには、エラーを示す JSON オブジェクトが渡されます。

monaca.InAppUpdater.forceStopDownload().then(
    function(str) { alert("stop success"); } ,
    function(fail) { alert( JSON.stringify(fail) ); }
);

updateAndRestart()

ダウンロードした更新用ファイルを展開し、アプリを再起動します。

monaca.InAppUpdater.updateAndRestart(): Promise

パラメーター

  • なし

戻り値 (Promise)

  • 成功時のコールバックには、結果を格納した JSON オブジェクトが渡されます。

  • 失敗時のコールバックには、エラーを示す JSON オブジェクトが渡されます。

  • 進捗表示コールバックには、展開処理の進捗状況を示す、次のような JSON オブジェクトが渡されます。

    名前 解説
    count 数値 Zip ファイルを展開して得られた、現在までのファイル数
    total 数値 展開予定の更新ファイル数

monaca.InAppUpdater.updateAndRestart().then(
    function() { },
    function(fail) { alert( JSON.stringify(fail) ); },
    function(json) { console.log( json.count + "/" + json.total + " are done." ); }
);

status()

プラグインの状態を確認します。

monaca.InAppUpdater.status(): Promise

パラメーター

  • なし

戻り値 (Promise)

  • 成功時のコールバックには、次のような内容の JSON オブジェクトが渡されます。

    名前 解説
    running 真偽値 プラグインが処理中の場合、true を返します。
    status 文字列 処理に関する情報が格納されています。
  • 失敗時のコールバックには、エラーを示す JSON オブジェクトが渡されます。

monaca.InAppUpdater.status().then(
    function(json) { alert( JSON.stringify(json) ); },
    function(fail) { alert( JSON.stringify(fail) ); }
);

showAlertDialog()

ダイアログ ( タイトルとメッセージ ) を表示します。

monaca.InAppUpdater.showAlertDialog(args: JSON object): Promise

パラメーター ( JSON オブジェクト)

プロパティ 解説
title 文字列 ダイアログのタイトル
message 文字列 メッセージ本文
button JSON オブジェクト ボタンは、次の 2 つの要素で構成されます。
  • label: [ 文字列 ] ボタンのラベル
  • handler: ボタンがクリックされたときに呼ばれる関数
例 :
{
    label : "OK",
    handler : function() { alert("OK is clicked"); }
}
cancel JSON オブジェクト キャンセルボタンは、次の 2 つの要素で構成されます。
  • label: [ 文字列 ] キャンセルボタンのラベル
  • handler: キャンセルボタンがクリックされたときに呼ばれる関数
例 :
{
    label : "Close",
    handler : function() { alert("Close is clicked"); }
}

戻り値 (Promise)

  • 成功時のコールバックには、結果を格納した JSON オブジェクトが渡されます。
  • 失敗時のコールバックには、エラーを示す JSON オブジェクトが渡されます。

monaca.InAppUpdater.showAlertDialog({
    title : "Title" ,
    message : "Message" ,
    button : { label : "OK" , handler : function() { alert( "OK is clicked"); } },
    cancel : { label : "Cancel" , handler : function() { alert( "Cancel is clicked"); } },
    dismiss : function() { alert("Dismissed!"); }
} ).then(
    function(btnLabel) { alert( "open" ); },
    function(fail) { alert( JSON.stringify(fail) ); }
);

dismissAlertDialog()

警告 ( Alert ) ダイアログを閉じます。

monaca.InAppUpdater.dismissAlertDialog(): Promise

パラメーター

  • なし

戻り値 (Promise)

  • 成功時のコールバックには、結果を格納した JSON オブジェクトが渡されます。
  • 失敗時のコールバックには、エラーを示す JSON オブジェクトが渡されます。

setTimeout( function() {
    monaca.InAppUpdater.dismissAlertDialog().then(
        function(json) { alert( "OK auto close" ); },
        function(fail) { alert( JSON.stringify(fail) ); }
    );
} , 1000 );

showProgressDialog()

進捗表示 ( Progress ) 用ダイアログを表示します。こちらのダイアログでは、更新の進捗状況が表示されます。

monaca.InAppUpdater.showProgressDialog(args: JSON object): Promise

パラメーター ( JSON オブジェクト)

プロパティ 解説
title 文字列 ダイアログのタイトル
message 文字列 メッセージ本文
max 数値 カウンターの最大値です。ファイルをダウンロードする場合には、ファイル総数となります。
progress 数値 進捗を示す値です。ファイルをダウンロードする場合には、ダウンロード済みのファイル総数となります。
cancel JSON オブジェクト キャンセルボタンは、次の 2 つの要素で構成されます。
  • label: [ 文字列 ] キャンセルボタンのラベル
  • handler: キャンセルボタンがクリックされたときに呼ばれる関数
例 :
{
    label : "Close",
    handler : function() { alert("Close is clicked"); }
}
dismiss コールバック関数 ダイアログを閉じたときに呼ばれる関数です。

戻り値 (Promise)

  • 成功時のコールバックには、結果を格納した JSON オブジェクトが渡されます。
  • 失敗時のコールバックには、エラーを示す JSON オブジェクトが渡されます。

monaca.InAppUpdater.showProgressDialog(
    { title : "Title" ,
    message : "Message" ,
    max : 100 ,
    progress : 50 ,
    cancel : { label : "Cancel" , handler : function() { log("cancel handler"); } } ,
    dismiss : function() { log("dismissed."); }
    } ).then(
    function(json) {
    alert(JSON.stringify(json));
    },
    function(fail) {
    alert( JSON.stringify(fail));
    }
);

changeProgressDialog()

進捗表示 ( Progress ) 用ダイアログを更新します。

monaca.InAppUpdater.changeProgressDialog(args: JSON object): Promise

パラメーター ( JSON オブジェクト)

プロパティ 解説
progress 数値 進捗を示す値

戻り値 (Promise)

  • 成功時にも引数は渡しません。
  • 失敗時のコールバックはありません。

monaca.InAppUpdater.changeProgressDialog( { progress: progress } ).then(
    function() {
    if (progress < 100) {
        setTimeout( function() { changeProgressDialog(progress+10); } , 500 );
    } else {
        monaca.InAppUpdater.dismissProgressDialog().then(
        function(json) { log("complete"); } ,
        function(error) { alert( JSON.stringify(error) ); }
        );
    }
    }
)

dismissProgressDialog()

進捗表示 ( Progress ) 用ダイアログを閉じます。

monaca.InAppUpdater.dismissProgressDialog(): Promise

パラメーター

  • なし

戻り値 (Promise)

  • 成功時のコールバックには、結果を格納した JSON オブジェクトが渡されます。
  • 失敗時のコールバックには、エラーを示す JSON オブジェクトが渡されます。

setTimeout( function() {
    monaca.InAppUpdater.dismissProgressDialog().then(
    function(json) { alert(JSON.stringify(json)); } ,
    function(error) { alert( JSON.stringify(error) ); }
    );
} , 1000 );

networkStatus()

ネットワークの状態 ( Wifi、3G/LTE、接続なし など ) を確認します。

monaca.InAppUpdater.networkStatus(): Promise

パラメーター

  • なし

戻り値 (Promise)

  • 成功時のコールバックには、次のような内容の JSON オブジェクトが渡されます。

    名前 解説
    network 真偽値 通信事業者のネットワークが利用できる場合には、true を返します。
    wifi 真偽値 WiFi が利用できる場合には、true を返します。
    mobile 真偽値 ネットワーク接続 ( 通信事業者のネットワークまたは WiFi ) を利用できる場合には true を返します。利用できない場合には、 false を返します。
  • 失敗時のコールバックには、エラーを示す JSON オブジェクトが渡されます。

monaca.InAppUpdater.networkStatus().then(
    function(json) { alert( JSON.stringify(json) ); },
    function(fail) { alert( JSON.stringify(fail) ); }
);

terminateApp()

アプリを強制終了します。

このメソッドは、旧 InAppUpdater ( Cordova 5 向けの v2.0.4 ) との互換性を維持するために提供されているメソッドです。
こちらはクラッシュに相当するので、iOS での使用は推奨しません。Apple 側から申請をリジェクトされる可能性があります。
monaca.InAppUpdater.terminateApp()

パラメーター

  • なし

戻り値 (Promise)

  • なし

monaca.InAppUpdater.terminateApp();

autoUpdate()

更新ファイルのダウンロードとアプリの更新を自動的に行います。

monaca.InAppUpdater.autoUpdate(options: JSON object): Promise

パラメーター ( JSON オブジェクト)

プロパティ 解説
connectDelay 数値 サーバー接続を開始するまでの待機時間 ( ミリ秒単位 )
dialogMessages JSON オブジェクト アプリの更新時に表示されるダイアログ。次の変数が使用できます。
  • confirm3G: [ 文字列 ] 更新ファイルのダウンロード時に、WiFi の代わりに通信事業者のネットワークを使用している場合に表示されるテキストです。
  • prepare: [ JSON オブジェクト ] 2 つの変数を格納したオブジェクトです。変数は、 titlemessage です。更新ファイルのダウンロードを開始 ( 準備 ) するときに表示されます。
  • download: [ JSON オブジェクト ] 2 つの変数を格納したオブジェクトです。変数は、 titlemessage です。更新ファイルをダウンロードしているときに表示されます。
例 :
{
    confirm3G : 'These updates will be downloaded with your mobile data.',
    prepare : {
        title : 'Preparing to Dowload the Updates',
        message : 'Now checking the server version ...'},
    download : {
        title : 'Dowloading the Updates',
        message : 'Now downloading ...'}
}
nextTask コールバック関数 更新成功時に呼ばれる関数
failTask コールバック関数 更新失敗時に呼ばれる関数

戻り値 (Promise)

  • なし

monaca.InAppUpdater.autoUpdate( {
    connectDelay : 0000,
    connectTimeout : 30000,
    readTimeout: 300000,
    nextTask : function(res) {
    if (res.requireRestart) {
        monaca.InAppUpdater.updateAndRestart().then(
        function() { },
        function(fail) { alert( JSON.stringify(fail) ); }
        );
    } else {
        alert("App is started!");
    }
    },
    failTask : function(res) {
    monaca.InAppUpdater.showAlertDialog(
        { title : "Error Code "+res.error.code ,
        message : res.error.message ,
        button : { label : "OK" , handler : function() { } }
        } ).then(
        function(json) {  },
        function(fail) { }
    );
    }
});