一覧に戻る

iOS ネイティブAPIのセットアップ

2017.09.22iOSネイティブAPI

セットアップ

Wikitude SDK ネイティブAPIを既存のiOSアプリケーションに追加するのは簡単です。このトピックではそのステップについて詳しく説明します。

前提条件

  • Xcode: Mac App Storeで利用できる。
  • iOS Development Certificateが有効になっている。

プロジェクトのセットアップ

XCODEプロジェクトのロード

既存のXcodeプロジェクトがある場合はプロジェクトを開きます。プロジェクトをまだ作成していない場合は、Xcodeで新規プロジェクトを作成します。

Wikitude SDK ネイティブAPIのフレームワークを追加

Wikitude SDK ネイティブAPIの.frameworkをXcodeプロジェクト構造にコピーします。マシン上の他の場所に置くと、新しいバージョンのWikitude SDK ネイティブAPIにアップデートするときに整合性が取れなくなる場合があります。
.frameworkをコピーした後、Embedded Binariesとして追加することができます。

アプリケーションでのWikitude SDK ネイティブAPIの使用

セットアップが完了すると、Wikitude SDK ネイティブAPIはiOSアプリケーション内で使用できる状態になります。
Wikitude SDK ネイティブAPIには、対応するソースファイルに含まれるアンブレラヘッダが付属しています。このファイルはWikitudeNativeSDK.hで、#import を呼び出してインポートできます。

メインクラスはWTWikitudeNativeSDKです。これは、トラッカーの作成、既に設定されているレンダリングコンポーネントの取得、またはカメラ関連の設定の制御が主な目的です。

Wikitude SDK ネイティブAPIは有料ライセンスなしのトライアル版で使用できますが、ウォーターマークを削除するには、-setLicenseKey:メソッドを使用して有効なライセンスを設定する必要があります。

アプリケーションライフサイクル

Wikitude SDK ネイティブAPIをアプリケーションライフサイクルに統合するには、WTWikitudeNativeSDKの-start:completion:メソッドと-stopメソッドを使用します。これらのメソッドを呼び出す場所として適しているのは、UIViewControllers -viewWillAppear:や-viewWillDisappear:などです。起動フェーズを細かく調整するには、-start:completion:の最初の引数としてWTStartupConfigurationオブジェクトを使用します。2番目のブロックパラメータを使用して、Wikitude SDK ネイティブAPIが現在のデバイスの構成で実際に起動できたかを確認できます。isRunningパラメータを使用して実行状態を確認し、このブロックでトラッカーの作成などを行います。これらを実行するコードサンプルを以下に示します。

[self.wikitudeSDK start:nil completion:^(BOOL isRunning, NSError * __nonnull error) {
    if ( !isRunning ) {
        NSLog(@"Wikitude SDK is not running. Reason: %@", [error localizedDescription]);
    }
    else
    {
        __weak typeof(self) weakSelf = self;

        NSURL *imageTrackerResourceURL = [[NSBundle mainBundle] URLForResource:@"magazine" withExtension:@"wtc" subdirectory:@"Assets"];
        self.targetCollectionResource = [self.wikitudeSDK.trackerManager createTargetCollectionResourceFromURL:imageTrackerResourceURL completion:^(BOOL success, NSError * _Nullable error) {
            if ( !success )
            {
                NSLog(@"Failed to load URL resource. Reason: %@", [error localizedDescription]);
            }
            else
            {
                weakSelf.imageTracker = [weakSelf.wikitudeSDK.trackerManager createImageTrackerFromTargetCollectionResource:weakSelf.targetCollectionResource delegate:weakSelf configuration:nil];
            }
        }];
    }
}];

エラー処理

内部的に不正な状態が検出され、SDKの一部が正しく動作していない可能性がある場合、WTWikitudeNativeSDKデリゲートメソッドの-wikitudeNativeSDK: didEncounterInternalError:がただちに呼び出されます。これは特にアプリケーションの開発中に活用できます。

カメラとレンダリングのトラッカー

トラッカー、カメラの制御およびレンダリングの使用方法については、サンプル部分で説明します。各機能については、実際の使用例を使って詳しく説明します。

App Storeの提出のためのシミュレータアーキテクチャの削除

XcodeのApp Store submission bugを回避するために、WikitudeNativeSDK.frameworkには、.frameworkからシミュレータアーキテクチャを削除するシェルスクリプトが含まれています。このスクリプトは、TerminalアプリケーションまたはXcodeのRun Script Phaseから実行できます。

ここでは、Terminalアプリケーションのスニペットを示します。スクリプトへのパスとWikitudeNativeSDK.frameworkへのパスを把握する必要があることに注意してください。

sh *PATH/TO/THE/WIKITUDE/SDK/PACKAGE*/Tools/Scripts/strip_wikitude_framework.sh -s -p *PATH/TO/THE/WikitudeNativeSDK.framework

Run Script Phaseでスクリプトを実行するには、新しいRun Script Phaseのテキストフィールドに以下のスニペットをコピーします。Embed Frameworksのビルドフェーズの直後にRun Script Phaseが配置されていることを確認してください。(個々のビルドフェーズの順序を変更できます。)

sh $BUILT_PRODUCTS_DIR/$FRAMEWORKS_FOLDER_PATH/WikitudeNativeSDK.framework/strip_wikitude_framework.sh -s -p $BUILT_PRODUCTS_DIR/$FRAMEWORKS_FOLDER_PATH/WikitudeNativeSDK.framework

Bitcode

WikitudeNativeSDK.frameworkは、App ThinningをサポートするためBitcode情報が含まれています。ビットコードを有効にした.frameworkをビルドするとファイルサイズが大きくなります。WikitudeNativeSDK.frameworkを使用するアプリケーションでビットコードがサポートされず、ファイルサイズが問題になる場合、ビットコードの情報はwikitude_bitcode.shシェルスクリプトを使用して削除できます。このスクリプトはTerminalアプリケーションまたはXcodeのRun Script Phaseで実行できます。Wikitudeはビルド時間が不必要に増加しないTerminalアプリケーションの使用を推奨します。

ここではTerminalアプリケーションのスニペットを示します。スクリプトへのパスとWikitudeNativeSDK.frameworkへのパスを把握しておく必要があることに注意してください。

sh *PATH/TO/THE/WIKITUDE/SDK/PACKAGE*/Tools/Scripts/wikitude_bitcode.sh -s -p *PATH/TO/THE/WikitudeNativeSDK.framework

ここではRun Script Phaseのスニペットを示します。スクリプトフェーズのテキストフィールドに以下のスニペットをコピーします。

sh $BUILT_PRODUCTS_DIR/$FRAMEWORKS_FOLDER_PATH/WikitudeNativeSDK.framework/wikitude_bitcode.sh -s -p $BUILT_PRODUCTS_DIR/$FRAMEWORKS_FOLDER_PATH/WikitudeNativeSDK.framework

SwiftでのWikitude SDK ネイティブAPIの使用

Wikitude SDK ネイティブAPIはObjective-Cでコードが書かれているため、本来はAppleのSwiftとは互換性があります。Wikitude SDK ネイティブAPIをSwiftで使用するには、Xcodeで新しい空のObjective-Cファイルを作成することでBridging-Headerを生成します。XcodeにはBridging-Headerを作成するかどうかを確認するメッセージが表示されるので、確認してHeaderを作成してください。空のObjective-Cファイルは削除できます。その後、Bridging-Headerに次の行を追加します。

#import <WikitudeNativeSDK/WikitudeNativeSDK.h>

SwiftからWikitude SDK ネイティブAPIのすべてのインターフェイスを呼び出すことができます。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:(WTWikitudeNativeSDK *)sdk;
{
    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:(WTWikitudeNativeSDK *)sdk
{
    [sdk removePlugin:_plugin];
}

@end

Swiftはプラグインを示すstd::shared_ptrを処理できないので、Objective-C++ラッパーに格納します。このプラグインの初期化には、UIViewControllerと同様に2つの整数値が必要です。プラグインに必要なパラメータに応じて、initメソッドを変更します。すべての入力プラグインはWikitude SDK ネイティブAPIから登録および登録解除をできる必要があるので、両方の目的のためにメソッドを作成します。