iOSセットアップガイド
Wikitude SDKをiOSアプリケーションに追加するために必要なステップはほんのわずかです。このガイドではそれらのステップについて詳しく説明します。
前提条件
- Xcode: Mac App Storeで利用できる。
- iOS Development Certificateが有効になっている。
Xcodeプロジェクトのロード
最初のステップは既存のXcodeプロジェクトを開くことです。使用可能なプロジェクトがない場合は、Xcodeプロジェクトセットアップウィザードを使用してプロジェクトを作成します。
Wikitude SDKフレームワークの追加
まず、プロジェクトにFrameworks
といった名前の新しいディレクトリを作成します。ダウンロードしたWikitude SDKフレームワークをこのディレクトリにコピーします。
Wikitude SDKフレームワークを適切な場所にコピーしたら、プロジェクト設定の[General]->[Embedded Binaries]
にてWikitude SDKフレームワークを追加します。(+マークをクリックします。)
ダイアログで、Wikitude SDKフレームワークを選択します。
ビルド設定の構成
Wikitude SDKでは、ビルド設定の変更は必要ありません。 完全にModule
とBitcode
に対応しているため、追加のシステムフレームワークやビルド設定を変更する必要はありません。
プロジェクトのInfo.plistの更新
Wikitude SDKでは、デバイスのカメラを使用します。カメラを使用するにはNSCameraUsageDescription
キーを設定し、アプリのユーザーにデバイスのカメラへのアクセスが必要な理由を説明する必要があります。説明用のテキストとし「ARオブジェクトをカメラビューに表示するには、カメラにアクセスする必要があります。」など任意のテキストを設定してください。
アプリでロケーションベース型ARを使用する場合は、NSLocationWhenInUsageDescription
キーに「ARコンテンツを表示するには、デバイスの位置情報にアクセスする必要があります。」のような説明用のテキストを設定します。
スクリーンショットの作成機能をカメラロールのエクスポートと組み合わされて使用する場合は、NSPhotoLibraryUsageDescription
キーが必要です。アクセスが必要な理由の説明用テキストを再度設定します。
アプリケーションでのSDKの使用
以上にて、Wikitude SDKをiOSアプリケーション内で使用する準備が整いました。使用するクラスはWTArchitectView
です。このUIView
のサブクラスを使用して、ARchitect Worldをロードできます。
Wikitude SDKはフレームワークなので、ヘッダのインポート文は次のようになります。#import <*FrameworkName*/*HeaderFile.h*>
。このインポートは通常、WTArchitectView
インスタンスを管理するUIViewController
サブクラスで行います。
#import <WikitudeSDK/WikitudeSDK.h>
WTArchitectView
およびWTNavigation
プロパティをUIViewController
サブクラスに追加するのが一般的な方法です。
@property (nonatomic, strong) WTArchitectView *architectView;
コードでWTArchitectView
型のインスタンスを初期化するには、-init
メソッドを使用します。 プロジェクトがStoryboardを使用する場合は、-initWithCoder:
も実装され、使用できる状態になります。
WTArchitectView
を初期化するコードを以下に示します。
- (void)viewDidLoad
{
// ... other initialization code ...
NSError *deviceNotSupportedError = nil;
if ( [WTArchitectView isDeviceSupportedForRequiredFeatures:WTFeature_Geo | WTFeature_ImageTracking error:&deviceNotSupportedError] ) { // 1
self.architectView = [[WTArchitectView alloc] init];
self.architectView.delegate = self;
self.architectView.requiredFeatures = WTFeature_ImageTracking; // 2
[self.architectView setLicenseKey:@"YOUR_LICENSE_KEY"]; // 3
[self.view addSubview:self.architectView]; // 4
// ...
} else {
NSLog(@"device is not supported - reason: %@", [deviceNotSupportedError localizedDescription]);
}
// ... continue initialization ...
}
-
isDeviceSupportedForRequiredFeatures:error:
メソッドを使用して、特定の機能要件を持つARchitect Worldを現在のデバイスで実行できるかどうかを判断します。詳細については、クラスリファレンスのWTArchitectView
を参照してください。 requiredFeatures
プロパティを使用して、使用するWikitude SDKの機能を指定します。 これは、必要なコンポーネントだけを開始するのに役立ちます。-
setLicenseKey:
メソッドを使用して、ライセンスキーを含む文字列を渡すことができます。無償のトライアルキーを入手するには、このセクションを参照してください。 -
WTArchitectViewインスタンスをアプリケーションのビュー階層に追加する必要があります。
カメラビューを開始/停止するには、WTArchitectView
の-start:completion
および-stop
メソッドを呼び出す必要があります。この目的のために、UIViewController
の-viewWillAppear:
および-viewWillDisappear:
メソッドを使用できます。アプリケーションはユーザーがデバイスのホームボタンを押すと、アクティブではなくなり、再びアプリケーションを選択することでアクティブになります。WTArchitectViewを管理するUIViewControllerが存在する場合、対応するこれらのメソッドが呼び出されるので、それにあわせてWTArchitectView
を開始/停止する必要があります。
ARchitect Worldのロード
ARchitect WorldをiOSアプリケーションに組み込むために必要なステップは、WikitudeSDK.frameworkをiOSアプリケーションに追加する方法とよく似ています。
- ARchitect WorldファイルをXcodeプロジェクトのフォルダ構造に追加します。
- ARchitect WorldファイルをXcodeプロジェクト自体に追加します。
- iOSアプリケーション内でARchitect Worldファイルを使用します。
次の図は、典型的なXcodeプロジェクトの構造を示します。ArchitectWorld
という名前の新しいフォルダを作成し、そこにARchitect Worldを追加します。
XcodeにARchitect Worldを追加するには、[File]
メニューから[Add Files to "プロジェクト名"]
を選択します。
[File]->[Open]
ダイアログで、メインのARchitectWorld
フォルダを選択します。
メモ: 必ず[Create folder references for any added Folders]
オプションをオンにしてください。これにより、すべてのファイルとサブフォルダがアプリケーションのリソースバンドルに同じ構造でコピーされます。また、後で追加したファイルも、アプリケーションをビルドするときに自動的にリソースバンドルに追加されます。
すべての手順が適切に完了したら、プロジェクトは次の図のようになります。
Architect Worldは、WTArchitectView
が提供する-loadArchitectWorldFromURL:
メソッドを使用してロードできます。 Architect World URLを取得するには、NSBundle
メソッドの-URLForResource:withExtension:subdirectory:
を使用します。
次のリストは、これら両方のメソッドの使用方法を示します。
NSURL *architectWorldURL = [[NSBundle mainBundle] URLForResource:@"index" withExtension:@"html" subdirectory:@"ArchitectWorld"];
[self.architectView loadArchitectWorldFromURL:architectWorldURL];
通常、WTArchitectView
インスタンスが生成されたときに実行されます。-start:completion:
/-stop
および-loadArchitectWorldFromURL:
メソッドはお互いに依存しないため、呼び出される順序は関係ありません。
WTArchitectViewが再開した場合、Architect Worldをもう一度ロードする必要はありません。別のArchitect Worldがロードされている間に新しいArchitect Worldをロードすると、現在のArchitect Worldのロードは破棄され、関連するオブジェクトとリソースはすべて解放されます。
メモ: 詳細については、GitHubに掲載された、WTArchitectView
の適切な処理方法を示すXcodeプロジェクトを参照してください。
SwiftでのWikitude SDKの使用
Wikitude SDKはObjective-Cでコードが書かれているため、本来はAppleのSwiftとは互換性があります。Wikitude Javascript SDKをSwiftで使用するには、Xcodeで新しい空のObjective-Cファイルを作成することでBridging-Headerを生成します。XcodeにはBridging-Headerを作成するかどうかを確認するメッセージが表示されるので、確認してHeaderを作成してください。空のObjective-Cファイルは削除できます。 その後、Bridging-Headerに次の行を追加します。
#import <WikitudeSDK/WikitudeSDK.h>
SwiftからWikitude SDKのすべてのインターフェイスを呼び出すことができます。Swiftにクラスを公開するにはBridging-HeaderにObjective-Cのヘッダをすべて追加します。Xcodeは自動的にSwiftインターフェイスを生成します。
Swiftと入力プラグイン
SwiftはObjective-CとObjective-C++のコードを自然に呼び出すことができますが、C++のコードを呼び出す機能はありません。入力プラグインを実行するには、Swift-C++の通信を有効にするために、Objective-C++のラッパークラスを中間体として作成する必要があります。次にBridging-HeaderにインポートすることでSwiftにラッパークラスを公開します。
これはSwiftサンプルのラッパークラスの実装です。ここではC++バーコードリーダーをアプリケーションに追加しています。
@implementation BarcodePluginWrapper
{
std::shared_ptr<wikitude::sdk::Plugin> _plugin;
}
- (id)initWithCameraWidth:(int)cameraWidth :(int)cameraHeight :(UIViewController *) viewController
{
self = [super init];
if (self)
{
_plugin = std::make_shared<BarcodePlugin>(cameraWidth, cameraHeight, viewController);
}
return self;
}
- (void)registerPluginWithSDK:(WTArchitectView *)architectView;
{
NSError *error = nil;
BOOL pluginRegistered = [sdk registerPlugin:_plugin error:&error];
if ( !pluginRegistered )
{
NSLog(@"Unable to register plugin '%@'. Error: %@", [NSString stringWithUTF8String:_plugin->getIdentifier().c_str()], [error localizedDescription]);
}
}
- (void)removePluginFromSDK:(WTArchitectView *)architectView
{
[sdk removePlugin:_plugin];
}
@end
Swiftはプラグインを示すstd::shared_ptr
を処理できないので、Objective-C++ラッパーに格納します。このプラグインの初期化には、UIViewController
と同様に2つの整数値が必要です。プラグインに必要なパラメータに応じて、initメソッドを変更します。すべての入力プラグインはWikitude SDKから登録および登録解除をできる必要があるので、両方の目的のためにメソッドを作成します。