一覧に戻る

Cordovaプラグインのセットアップ

2017.06.15Cordovaプラグイン

ArchitectView

Wikitude SDKでは、「ArchitectView」と呼ばれるWebビューを拡張したUIコンポーネントを提供します。ArchitectViewでは標準のWebビューでは実装できない、AR体験をレンダリングできます。
ArchitectView用のコンテンツは、JavaScriptとHTMLを使用して開発されます。ArchitectView用の*.htmlおよび*.jsファイルは、Cordova用の*.htmlおよび*.jsファイルと異なります。

前提条件

  • Androidアプリ開発の場合、開発用PCにAndroid SDKがインストールされている必要があります。
  • iOSアプリ開発の場合、開発用PCにXcodeがインストールされている必要があります。
  • CordovaCLIがnpmを介して開発用PCにインストールされている必要があります。

セットアップと構成

Wikitude Cordovaプラグインを使用してWikitude SDKをセットアップする方法を複数のセクションで説明します。セクションの構成は以下のとおりです。

  • 新規アプリの作成
  • 既存アプリにWikitude Cordovaプラグインを追加
  • サンプルアプリのセットアップ
  • Wikitude Cordovaプラグインの使用方法

バージョンと互換性

Cordova

PhoneGap - iOS

PhoneGap - Android

Wikitude Cordovaプラグイン

4.3.0

3.8.0

3.7.1

4.1.0 – 3.0.x

5.0.0

3.8.0

4.0.0

4.1.0 – 3.1.x以降

新規アプリの作成

  1. コンソールを起動して、新規アプリを作成したい任意のディレクトリに移動します。

  2. Cordova CLIを使用して新しいCordovaプロジェクトを作成します。

    $ cordova create AugmentedRealityProject com.yourid.arsample ARProject

    プロジェクトディレクトリとして「AugmentedRealityProject」ディレクトリを作成します。アプリのパッケージ名、および実際のアプリ名を指定するその他の2つのパラメータも引数として設定します。
    処理が成功すると、下記のメッセージが表示されます。

    $ Creating a new cordova project with name "AugmentedRealityProject" and id "com.yourid.arsample" at location "/Users/pete/Projects/ARProject"
    $ Downloading cordova library for www...
    $ Download complete
  3. プロジェクトディレクトリに移動します。

    $ cd AugmentedRealityProject

    プロジェクトディレクトリの構成は以下のようになります。

    - AugmentedRealityProject
    |- hooks
    |- merges
    |- platforms
    |- plugins
    |- www
  4. アプリを作成するプラットフォームを追加します。プラットフォームの追加は、対応するネイティブSDKが開発システム上にインストールされている必要があります。(例:Windowsシステム上にiOSを追加できません)。本セクションでは、MacOSがインストールされているシステムを使用して、iOSとAndroid用のアプリを作成することを想定しています。

    まずはiOSのプラットフォームを追加します。

    $ cordova platform add ios

    処理が成功すると、下記のメッセージが表示されます。

    $ Downloading cordova library for ios...
    $ Download complete
    $ Creating ios project...

    ビルドを実行します。

    $ cordova build ios

    アプリのビルドとコンパイル処理の完了後、下記のようなメッセージが表示されます。

    $ ** BUILD SUCCEEDED **

    同様に、Androidプラットフォームを追加します。

    $ cordova platform add android 
    $ cordova build android

    処理が成功すると、下記のメッセージが表示されます。

    $ BUILD SUCCESSFUL 
    $ Total time:   30 seconds
  5. Wikitude CordovaプラグインをインストールしてプロジェクトにWikitude SDKを追加します。

    $ cordova plugin add https://github.com/Wikitude/wikitude-cordova-plugin.git

    プラグインがGitHubからクローン化されダウンロード(30MB以上)されます。プラグインのインストール処理にはしばらく時間がかかります。場合によっては1分以上かかる場合もあります。
    処理が成功すると、下記のメッセージが表示されます。

    $ Plugin "com.wikitude.phonegap.WikitudePlugin" fetched.

    プロジェクトディレクトリの構成は以下のようになります。

    - AugmentedRealityProject
    |- hooks
    |- merges
    |- platforms
         |- android
         |- ios
    |- plugins
         |- com.wikitude.phonegap.WikitudePlugin
    |- www
  6. プラグイン追加後、アプリをリビルドします。

    $ cordova build

    これで、Wikitude SDKを含むCordovaベースの新しいアプリを作成できました。Xcode、およびAndroid Studioでアプリを起動してみてください。

    • iOS
      • platforms/iosフォルダーへ移動し、.xcodeprojectファイルをクリックしてXcodeでプロジェクトを開きます。
    • Android Studio
      • Android Studioを起動します。
      • Open an existing Android Studio projectをクリックします。
      • 表示されたダイアログで、your project root/platforms/androidへ移動し、chooseをクリックします。
      • 前のステップの後、Import project from gradleのダイアログが表示される場合は、プロジェクトのパスから/gradleを削除し、okをクリックします。

以上が新規アプリの作成方法となります。

既存アプリにWikitude Cordovaプラグインを追加

  1. コンソールを起動して、既存アプリのプロジェクトディレクトリに移動します。

  2. Wikitude CordovaプラグインをインストールしてプロジェクトにWikitude SDKを追加します。

    $ cordova plugin add https://github.com/Wikitude/wikitude-cordova-plugin.git

    プラグインが既存アプリに追加されます。

  3. プラグイン追加後、アプリをビルドします。

    $ cordova build

サンプルアプリのセットアップ

Wikitude Cordovaプラグインを使用し構成されているサンプルアプリが提供されています。このサンプルアプリでは、Wikitude Cordovaプラグイン、および ARchitectViewの使用方法を確認できます。

サンプルアプリの自動セットアップ

  1. GitHubからサンプルアプリをダウンロードします。

  2. ダウンロードファイルを解凍します。

  3. コンソールを開き、ファイルを解凍したディレクトリに移動します。

  4. コンソールで、CreateSampleApp.shスクリプトを実行します。サンプルアプリを作成する場所を指定するには、-dオプションを使用します。-iosと-androidオプションにてコンパイル対象のプラットフォームを指定できます。

    $ ./CreateSampleApp.sh -d ~/Path/Where/The/App/Should/Be/Created -ios true -android true

    プラグインがGitHubからクローン化されダウンロード(30MB以上)されます。プラグインのインストール処理にはしばらく時間がかかります。場合によっては1分以上かかる場合もあります。
    処理が成功すると、下記のメッセージが表示されます。

    $ *** DONE - SUCCESS ***
  5. これで、Wikitude SDKを含むCordovaベースの新しいアプリを作成できました。Xcode、およびAndroid Studioでアプリを起動してみてください。

以上が新規アプリの作成方法となります。

サンプルアプリを手動で追加する方法

既存のアプリにサンプルアプリを手動で追加するには、サンプルアプリのリソースを既存のアプリのプロジェクトディレクトリにコピーして、リビルドする必要があります。

  1. GitHubからサンプルアプリをダウンロードします。

  2. ダウンロードファイルを解凍します。

  3. 下記のとおり、サンプルアプリのリソースを既存のアプリのプロジェクトディレクトリにコピーします。

    • SampleAppResources/cssにある全てのファイルをwww/cssディレクトリにコピーします。
    • SampleAppResources/jsにある全てのファイルを www/jsディレクトリにコピーします。
    • SampleAppResources/jqueryディレクトリをwww/ディレクトリにコピーします。
    • SampleAppResources/worldディレクトリをwww/ディレクトリにコピーします。
    • index.htmlをSampleAppResources/からwww/にコピーします。

    プロジェクトディレクトリの構成は以下のようになります。

    PROJECT_DIRECTORY |- hooks |- merges |- platforms |- plugins |- com.wikitude.phonegap.WikitudePlugin |- www
    |- css
    |- index.css
      |- jquery.mobile.structure-1.3.2.min.css
    |- index.html
    |- jquery
        |- (more files)
    |- js
        |- index.js
    |- world
        |- (more files)           
  4. プラグイン追加後、アプリをリビルドします。

Wikitude Cordovaプラグインの使用方法

Wikitude Cordovaプラグインを追加後、アプリにそのプラグインを使用して、ARchitect Worldをロードし表示することができます。CordovaアプリとARchitect Worldの両方がHTMLとJavaScriptで記述されていますが、Wikitude SDKではCordovaアプリのWebビューの代わりに独自のWebビューであるArchitectView使用しているためそれらが相互に直接通信することはできません。したがって、直接通信を可能にするために、コールバックメカニズムを使用する機能が実装されています。
次のセクションに記載されているサンプルコードは、Cordovaアプリに実装されることを想定しています。たとえば、index.jsに実装されているイメージです。

ARchitect Worldのロード

WikitudePlugin.jsファイルを使用します。Wikitude Cordovaプラグインのインスタンスを生成するには、プラグインIDを使用してcordova.require()関数を呼び出します。

cordova.require("com.wikitude.phonegap.WikitudePlugin.WikitudePlugin")

上記は、Cordovaが提供しているonDeviceReady()関数に実装します。cordova.require()関数の戻り値を変数として格納します。サンプルアプリでは、index.jsに定義されているappオブジェクトに格納しています。

app.wikitudePlugin = cordova.require("com.wikitude.phonegap.WikitudePlugin.WikitudePlugin")

プラグイン生成の完了後、最初にデバイスでAR体験が実行できることを確認します。Wikitude SDKの詳細な要件については、こちらをご参照ください。デバイスがサポートされているかどうか、および必要な機能を確認するコールバックを提供するためのisDeviceSupported(successCallback, errorCallback, requiredFeatures)関数を使用できます。必要な機能のリストに利用可能なすべてのオプションを設定します。このAR体験が画像認識型AR「2d_tracking」)とロケーションベース型AR(「geo」)の両方を使用することを定義します。もし、独自のAR体験が画像認識型AR(「2d_tracking」)とロケーションベース型AR(「geo」)のどちらか一つだけを使用している場合には、配列に必要な文字列のみを渡してください。画像認識型ARのみを実行する場合、コンパスがないデバイスを拒否する必要があります。実行する呼び出しは次のようになります。

var app = {

    requiredFeatures: [ "2d_tracking", "geo" ],
    // ... some code ...

    onDeviceReady: function() {
        app.wikitudePlugin = cordova.require("com.wikitude.phonegap.WikitudePlugin.WikitudePlugin");
        app.wikitudePlugin.isDeviceSupported(app.onDeviceSupported, app.onDeviceNotSupported, app.requiredFeatures);
    },
    onDeviceSupported: function() {
        // ... code that is executed if the device is supported ...
    },
    onDeviceNotSupported: function(errorMessage) {
        // ... code that is executed if the device is not supported ...
    },

    // ... some more code ...

};

successCallbackでは、アプリにバンドルされた、またはリモートURLのいずれかからARchitect Worldをロードできます。実行する関数は次の通りです。

loadARchitectWorld(loadedSuccessful-Callback, loadError-Callback, "path/to/your/experience", requiredFeatures, startupConfiguration)

loadedSuccessful-CallbackとloadError-Callbackパラメータを使用すると、ARchitect Worldがロードする場合とURLにアクセスできないの場合に呼び出されるコールバック関数を設定することができます。3番目のパラメータは、独自のARchitect WorldへのURL、もしくはパスを定義します。4番目のパラメータは、ロードしようとしている特定のARchitect Worldに必要な機能を定義します。最後のパラメータを使用すると、追加のスタートアップ設定を定義できます。下記のサンプルコードでは、利用可能な両方の機能をアクティブ化しています。また、スタートアップ設定には、JSONオブジェクトを定義してバックカメラを使用することを設定しています。フロントカメラを使用する場合は、'camera_position'をfrontに設定します。デバイスには、バックとフロントカメラの1つだけが搭載されている場合は、定義されているカメラにかかわらず利用可能なカメラが使用されることにご注意ください。現時点では、camera_positionの設定だけを定義でき、Wikitude SDKの以降バージョンで他の設定も定義できるようになる予定です。実行する呼び出しは次のようになります。

var app = {

    requiredFeatures: [ "2d_tracking", "geo" ],
    arExperienceUrl: "www/experience/index.html",
    isDeviceSupported: false,
    startupConfiguration:
    {
        "camera_position": "back"
    },

    // ... some code ...

    onDeviceReady: function() {
        app.wikitudePlugin = cordova.require("com.wikitude.phonegap.WikitudePlugin.WikitudePlugin");
        app.wikitudePlugin.isDeviceSupported(app.onDeviceSupported, app.onDeviceNotSupported, app.requiredFeatures);
    },
    onDeviceSupported: function() {
        app.wikitudePlugin.loadARchitectWorld(
            app.onARExperienceLoadedSuccessful,
            app.onARExperienceLoadError,
            app.arExperienceUrl,
            app.requiredFeatures,
            app.startupConfiguration
        );
    },

    // ... some code ...

    onARExperienceLoadedSuccessful: function(loadedURL) {
        // ... do something when the augmented reality experience finished loading
    },
    onARExperienceLoadError: function(errorMessage) {
        // ... react on failures. That could be happen when the local path is wrong or the remote url returned an error code
    }

    // ... some code ...

};

ARchitect Worldをロードするには、これだけの処理が必要です。全ての実装を含んだサンプルコード次の通りです。

var app = {

    // Url/Path to the augmented reality experience you would like to load
    arExperienceUrl: "www/experience/index.html",
    // The features your augmented reality experience requires, only define the ones you really need
    requiredFeatures: [ "2d_tracking", "geo" ],
    // Represents the device capability of launching augmented reality experiences with specific features
    isDeviceSupported: false,
    // Additional startup settings, for now the only setting available is camera_position (back|front)
    startupConfiguration:
    {
        "camera_position": "back"
    },
    // Application Constructor
    initialize: function() {
        this.bindEvents();
    },
    // Bind Event Listeners
    //
    // Bind any events that are required on startup. Common events are:
    // 'load', 'deviceready', 'offline', and 'online'.
    bindEvents: function() {
        document.addEventListener('deviceready', this.onDeviceReady, false);
    },
    // deviceready Event Handler
    onDeviceReady: function() {
        app.wikitudePlugin = cordova.require("com.wikitude.phonegap.WikitudePlugin.WikitudePlugin");
        app.wikitudePlugin.isDeviceSupported(app.onDeviceSupported, app.onDeviceNotSupported, app.requiredFeatures);
    },
    // Callback if the device supports all required features
    onDeviceSupported: function() {
        app.wikitudePlugin.loadARchitectWorld(
            app.onARExperienceLoadedSuccessful,
            app.onARExperienceLoadError,
            app.arExperienceUrl,
            app.requiredFeatures,
            app.startupConfiguration
        );
    },
    // Callback if the device does not support all required features
    onDeviceNotSupported: function(errorMessage) {
        alert(errorMessage);
    },
    // Callback if your AR experience loaded successful
    onARExperienceLoadedSuccessful: function(loadedURL) {
        /* Respond to successful augmented reality experience loading if you need to */
    },
    // Callback if your AR experience did not load successful
    onARExperienceLoadError: function(errorMessage) {
        alert('Loading AR web view failed: ' + errorMessage);
    }

};

app.initialize();

CordovaアプリとARchitect Worldの通信

CordovaアプリとARchitect Worldの通信には、Wikitude CordovaプラグインのcallJavaScript(javaScript)関数を使用できます。JavaScriptはARchitect Worldのコンテキストで評価されます。この関数を呼び出す時は、ARchitect Worldが完全にロードされていない場合は、ARchitect Worldがロードされた後に評価されます。実行する呼び出しは次のようになります。

var app = {

    // ... some code ...

    onDeviceReady: function() {
        // ... onDeviceReady implementation
    },
    onDeviceSupported: function() {
        // ... code that is executed if the device is supported ...
    },
    onDeviceNotSupported: function(errorMessage) {
        // ... code that is executed if the device is not supported ...
    },
    onARExperienceLoadedSuccessful: function() {
        // NOTE: The 'createCircle(location, color)' function is defined in the AR experience
        app.wikitudePlugin.callJavaScript('createCircle(new AR.RelativeLocation(null, -10, 0), \'#97FF18\');');
    }
    // ... some more code ...

};

ARchitect WorldからCordovaアプリに通信するには、Wikitude SDKのカスタムスキームを使用することができます。AR.platform.sendJSONObjectがリクエストされた度に呼び出されるCordovaアプリケーション関数を設定できます。コールバックを設定するには、WikitudeプラグインのsetOnJSONObjectReceivedCallback(callback)関数を使用します。これは、ARchitect Worldのロード直前に実行できます。

var app = {

    // ... some code ...

    onDeviceReady: function() {
        // ... onDeviceReady implementation
    },
    onDeviceSupported: function() {

        // setting up a callback to communicate from ARchitect into PhoneGap
        app.wikitudePlugin.setOnJSONObjectReceivedCallback(app.onJSONObjectReceived);

        app.wikitudePlugin.loadARchitectWorld(
            app.onARExperienceLoadedSuccessful,
            app.onARExperienceLoadError,
            app.arExperienceUrl,
            app.requiredFeatures,
            app.startupConfiguration
        );
    },
    onDeviceNotSupported: function(errorMessage) {
        // ... code that is executed if the device is not supported ...
    },
    // ... some more code ...

};

Wikitude Cordovaプラグインでは、カスタムロケーションを設定する、スクリーンショットを取得するなどの機能も提供しています。これらの機能の使用方法については、WikitudePlugin.jsをご参照ください。