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

In-App アップデーター プラグインは、アプリの再ビルド・再パッケージ化を行わずに、アプリで使用している HTML5 アセットを更新するためのプラグインです。

In-App アップデーター プラグインを使用する場合は、別途、更新ファイルをホストする Web サーバーが必要になります (アプリから、これらのファイルへアクセスできること )。

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

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

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

プラグインの追加方法

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

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

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

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

使い方

In-App アップデーター プラグインは、対象アプリのバージョンに対して、HTML5 アセットを更新します。 HTML5 アセットを更新する場合は、Web サーバー側の更新ファイルに新しい更新番号の設定を行います。

Web サーバー側の更新ファイルについては、CheckUpdate URL を参照ください。

プラグインの設定

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

CheckUpdate URL

Web サーバー側の更新ファイルに設定されている更新バージョンを確認します。

Request パラメーター

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

Response パラメーター

成功時のレスポンス例

{
  "ios": {
    "2.1.0": { // アプリのバージョン
      "1": { // 更新番号
        "date": 20170113,
        "url": "https://hogehoge.com/app/ios-v2.1.0.zip" // オプション
      }
    }
  }
}

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

{
  "ios": {
    "2.1.0": { // アプリのバージョン
      "1": { // 更新番号
        "date": 20170113,
        "url": "https://hogehoge.com/app/1/ios-v2.1.0.zip" //  オプション
      },
      "2": { // 更新番号
        "date": 20170113,
        "url": "https://hogehoge.com/app/2/ios-v2.1.0.zip" //  オプション
      }
    },
    "2.2.0": { // アプリのバージョン
      "1": { // 更新番号
        "date": 20170210,
        "url": "https://hogehoge.com/app/1/ios-v2.2.0.zip" //  オプション
      }
    }
  }
}

上の例に示すように、更新番号の値は「日付」「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() 警告ダイアログを閉じます。
showProgressDialog() 進捗表示用ダイアログを表示します。
changeProgressDialog() 進捗表示用ダイアログを更新します。
dismissProgressDialog() 進捗表示用ダイアログを閉じます。
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": { // アプリのバージョン
          "1": { // 更新番号
            "date": 20170113,
            "url": "https://hogehoge.com/app/ios-v2.1.0.zip" // オプション
          }
        }
      }
    }
    
    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) { }
    );
    }
});