Mobile Platform as a Service:クイックスタート

本トピックでは、CocoaPods を使用して、既存の iOS クライアントプロジェクトに H5 コンテナーおよびオフラインパッケージコンポーネントを統合する方法について説明します。

SDK の使用

この Topic では、公式の H5 コンテナーおよびオフライン パッケージ デモを使用して、ベースライン 10.1.60 以降での H5 コンテナー SDK の使用方法について説明します。

H5 コンテナー SDK の使用手順は、以下の 5 つのステップで構成されます：

1. 構成の初期化

2. コンテナーの呼び出し

3. H5 とネイティブ間の双方向通信の有効化

4. オフラインパッケージの読み込み

5. H5 コンテナーのイベントトラッキング

1. 構成の初期化

1.1. コンテナーの初期化

• Nebula コンテナーを使用するには、アプリケーション起動後に SDK を呼び出してコンテナーを初期化する必要があります。この初期化処理は、- (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions メソッド内で DTFrameworkInterface クラスのメソッドとして実行する必要があります。mPaaS フレームワークが提供する DTFrameworkInterface + (ProjectName) カテゴリ内で、このメソッドをオーバーライドしてください。

    - (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
        // コンテナーの初期化
        [MPNebulaAdapterInterface initNebula];
    }

• 事前設定済みオフラインパッケージ、カスタム JSAPI、プラグイン などの機能を利用する場合は、initNebula インターフェイスを initNebulaWith インターフェイスに置き換え、必要なパラメーターを渡してコンテナーを初期化します。

  • presetApplistPath：カスタム事前設定済みオフラインパッケージのパッケージ情報ファイルのパス。

  • appPackagePath：カスタム事前設定済みオフラインパッケージのパス。

  • pluginsJsapisPath：カスタム JSAPI およびプラグインファイルのストレージパス。

    - (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
        // コンテナーの初期化
        NSString *presetApplistPath = [[NSBundle mainBundle] pathForResource:[NSString stringWithFormat:@"MPCustomPresetApps.bundle/h5_json.json"] ofType:nil];
        NSString *appPackagePath = [[NSBundle mainBundle] pathForResource:[NSString stringWithFormat:@"MPCustomPresetApps.bundle"] ofType:nil];
        NSString *pluginsJsapisPath = [[NSBundle mainBundle] pathForResource:[NSString stringWithFormat:@"Poseidon-UserDefine-Extra-Config.plist"] ofType:nil];
        [MPNebulaAdapterInterface initNebulaWithCustomPresetApplistPath:presetApplistPath customPresetAppPackagePath:appPackagePath customPluginsJsapisPath:pluginsJsapisPath];
    }

    説明

    initNebula および initNebulaWithCustomPresetApplistPath メソッドは相互排他であり、同時に呼び出すことはできません。

• mPaaS では、ミニアプリパッケージのリクエスト間隔を、グローバルまたは個別に構成できます。

  • グローバル構成：コンテナー初期化時に以下のコードを使用して、オフラインパッケージまたはミニアプリの更新頻度を設定できます。

    [MPNebulaAdapterInterface shareInstance].nebulaUpdateReqRate = 7200;

    上記コードの `7200` は、デフォルトのグローバル更新間隔（秒単位）です。この値を変更することで、オフラインパッケージのカスタムグローバルリクエスト間隔を設定できます。有効範囲は 0～86400 秒（24 時間）です。値が 0 の場合、リクエスト間隔に制限はありません。

  • 個別構成：これは、単一のミニアプリパッケージの間隔を構成します。コンソールで、個別構成 > オフラインパッケージの追加 > 拡張情報 に移動し、リクエスト間隔を設定するために {"asyncReqRate":"1800"} を入力します。詳細については、「H5 オフラインパッケージの作成」の 拡張情報 セクションをご参照ください。

1.2 コンテナーのカスタマイズ

• 必要に応じて、MPNebulaAdapterInterface のプロパティを設定することで、コンテナーをカスタマイズできます。これらのプロパティは、- (void)application:(UIApplication *)application afterDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions メソッド内で DTFrameworkInterface クラスのメソッドとして設定する必要があります。それ以外の場合、コンテナーのデフォルト構成により、カスタム設定が上書きされます。

    - (void)application:(UIApplication *)application afterDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
        // コンテナーのカスタマイズ
        [MPNebulaAdapterInterface shareInstance].nebulaVeiwControllerClass = [MPH5WebViewController class];
        [MPNebulaAdapterInterface shareInstance].nebulaNeedVerify = NO;
        [MPNebulaAdapterInterface shareInstance].nebulaUserAgent = @"mPaaS/Portal";
        [MPNebulaAdapterInterface shareInstance].nebulaCommonResourceAppList = @[@"77777777"];
    }

• 各プロパティの説明は以下のとおりです：

  プロパティ	意味	備考
  nebulaViewControllerClass	HTML5 ページの基底クラス。	デフォルトは `H5WebViewController` です。すべての HTML5 ページに対してカスタム基底クラスを指定する場合は、このプロパティを設定します。 重要 基底クラスは、H5WebViewController を継承している必要があります。
  nebulaWebViewClass	WebView の基底クラスを設定します。	> 10.1.60: デフォルトでは H5WKWebView になります。カスタム WebView は、H5WKWebView を継承する必要があります。 = 10.1.60: カスタマイズはサポートされていません。
  nebulaUseWKArbitrary	オフラインパッケージページの読み込みに WKWebView を使用するかどうかを設定します。	> 10.1.60: デフォルトは YES です。 = 10.1.60: デフォルトは NO です。
  nebulaUserAgent	アプリケーションの User-Agent を設定します。	指定された User-Agent は、コンテナーのデフォルト UA に追加されます。
  nebulaNeedVerify	署名検証を実行するかどうかを指定します。デフォルト値は YES です。	オフラインパッケージの 構成時 に秘密鍵ファイルをアップロードしなかった場合は、この値を NO に設定してください。そうしないと、オフラインパッケージの読み込みに失敗します。
  nebulaPublicKeyPath	オフラインパッケージ署名検証用の公開鍵のパス。	オフラインパッケージの 構成時 にアップロードした秘密鍵に対応する公開鍵のパス。
  nebulaCommonResourceAppList	共通リソースパッケージの appIds のリスト。	-
  errorHtmlPath	HTML5 ページの読み込みに失敗した際に表示する HTML エラーページのパス。	デフォルトでは、コンテナーが MPNebulaAdapter.bundle/error.html から読み取ります。
  configDelegate	カスタムスイッチのデリゲートを設定します。	コンテナーのデフォルトスイッチ値をグローバルに変更できます。

1.3 フレームワーク非管理型構成

ご利用のアプリケーションのライフサイクルが mPaaS フレームワークによって管理されていない場合（フレームワーク非管理型プロジェクト）、本セクションで説明する追加構成を実行する必要があります。このシナリオでは、アプリケーションのライフサイクルがカスタムデリゲートに割り当てられます。mPaaS フレームワークがアプリケーションのライフサイクルを管理している場合は、追加構成は不要です。

• アプリケーションの `window` および `navigationController` が作成された後、以下のメソッドを呼び出します。ブートローダーの作成やフレームワークウィンドウの非表示化は不要です。

• DFNavigationController を継承する必要はありません。

• アプリケーションに複数のナビゲーションバーがあり、異なるナビゲーションバーで異なるオフラインパッケージを開く必要がある場合、切り替え後にコンテナーのナビゲーションバーを再設定する必要があります。

1.5. フレームワーク非管理型プロジェクトの構成（10.1.68.25 より前のバージョン向け）

ご利用のアプリケーションのライフサイクルが mPaaS フレームワークによって管理されていない場合（フレームワーク非管理型プロジェクト）、以下の追加構成を実行する必要があります。mPaaS フレームワークがアプリケーションのライフサイクルを管理している場合は、追加構成は不要です。

1.4.1 mPaaS フレームワークの起動

現在のアプリケーションの didFinishLaunchingWithOptions メソッド内で、[[DTFrameworkInterface sharedInstance] manualInitMpaasFrameworkWithApplication:application launchOptions:launchOptions]; を呼び出して、mPaaS フレームワークを起動します。

1.4.2 アプリケーションランチャーの作成

`DTBootLoader` を継承する子クラスを作成します。この子クラス内で、createWindow および createNavigationController メソッドを再書き込みし、現在のアプリケーションの `window` および `navigationController` を返すようにします。

• `window` の設定：現在のアプリケーションの `keyWindow`。

• `navigationController` の設定：現在のアプリケーションの `keyWindow` の `rootViewController`。これは `DFNavigationController` を継承している必要があります。

1.4.3 アプリケーションランチャーの指定

`DTFrameworkInterface` カテゴリ内で、mPaaS フレームワークのデフォルトウィンドウおよびランチャーアプリケーションを非表示にし、ご利用のアプリケーションのカスタムブートローダーを指定するメソッドを再書き込みます。

2. コンテナーの呼び出し

コンテナーが初期化された後、以下の 3 つの方法のいずれかで H5 コンテナーを呼び出すことができます。

• オンライン URL またはローカル HTML ファイルに基づいて H5 コンテナーを作成します。以下のコード例をご参照ください：

  // オンライン URL を開く
  [[MPNebulaAdapterInterface shareInstance] startH5ViewControllerWithParams:@{@"url": @"https://tech.antfin.com/products/MPAAS"}];
  // ローカル HTML ページを開く
  NSString *path = [[NSBundle mainBundle].bundlePath stringByAppendingFormat:@"/%@/%@", @"MPH5Demo.bundle", @"H52Native.html"];
  if ([path length] > 0) {
  [[MPNebulaAdapterInterface shareInstance] startH5ViewControllerWithParams:@{@"url": path}];
  }

• オフラインパッケージ情報を含むプッシュを使用して、H5 コンテナーを作成し、自動的に開きます。以下のコード例をご参照ください：

    [[MPNebulaAdapterInterface shareInstance] startH5ViewControllerWithNebulaApp:@{@"appId":@"90000000"}];

• オフラインパッケージ情報を元に H5 コンテナーを作成し、H5 コンテナーのインスタンスを返します。このメソッドは、通常、ホームページのタブで使用されます。以下のコード例をご参照ください：

    [[MPNebulaAdapterInterface shareInstance] createH5ViewControllerWithNebulaApp:@{@"appId":@"90000000"}];

3. H5 とネイティブ間の双方向通信の有効化

JSAPI の呼び出しおよび特定のイベントのリスニングにより、H5 とネイティブ間の双方向通信を有効化できます。

3.1. HTML5 ページからのネイティブ機能の呼び出し

H5 からネイティブへの通信は、JSAPI の呼び出しにより有効化できます。

Nebula コンテナーがサポートする JSAPI およびそのパラメーターの詳細については、「組み込み JSAPI」をご参照ください。

例

HTML5 ページ上のボタンがクリックされたときに、JSAPI メソッド pushWindow を呼び出して新しいページを読み込みます：

AlipayJSBridge.call('pushWindow', {
    url: 'https://tech.antfin.com',
    param: {
    readTitle: true,
    defaultTitle: true,
    // ...
    }
}, function(data) {alert('Call result'+JSON.stringify(data)); });

AlipayJSBridge の説明

AlipayJSBridge は、Nebula コンテナーにより自動的に注入される JSBridge です。Window.onload イベント発生後に、コンテナーはグローバル変数 `AlipayJSBridge` を生成し、`AlipayJSBridgeReady` イベントをトリガーします。注入は非同期処理であるため、インターフェイスを呼び出す前に `AlipayJSBridgeReady` イベントをリスニングする必要があります。

以下のコード例をご参照ください：

<h1>ブリッジの使用方法</h1>

<script>
function ready(callback) {
  if (window.AlipayJSBridge) {
    callback && callback();
  } else {
    document.addEventListener('AlipayJSBridgeReady', callback, false);
  }
}

ready(function(){
  alert('bridge ready');
});
</script>

3.2. ネイティブページからの H5 機能の呼び出し

ネイティブから H5 への通信は、特定のイベントのリスニングにより有効化できます。Nebula コンテナーがサポートするイベントの詳細については、「イベント拡張リスト」をご参照ください。

document.addEventListener('back', function (e) {
    if(confirm('戻るイベントがインターセプトされました。本当に戻りますか？')) {
        // 何らかの処理；
    }
}, false);

Nebula コンテナーがデフォルトでサポートするイベントに加えて、フロントエンドがリスニングできるカスタムイベントをネイティブ側で定義することもできます。

// self：現在の HTML5 ページが配置されている VC
// data：ネイティブからフロントエンドへ渡されるパラメーター
// callBack：フロントエンドがイベントを受信した後のコールバック
[self callHandler:@"customEvent" data:@{@"key":@"value"} responseCallback:^(id responseData) {
        NSLog(@"フロントエンドがイベントを受信した後のコールバック：%@", responseData);
    }];

3.3. Nebula コンテナー機能の拡張

Nebula コンテナーが提供する HTML5 ページ向けの基本的な双方向通信機能が要件を満たさない場合、Nebula を拡張できます：

• JSAPI：HTML5 ページからネイティブ機能（例：アクションシートや連絡先ダイアログボックスの表示）を呼び出したい場合、JSAPI を拡張する必要があります。JSAPI を使用すると、ハンドラーメソッドを用いて、HTML5 ページに簡単にネイティブ機能呼び出しを追加し、特定の機能を実装できます。JSAPI のカスタマイズ方法については、「JSAPI のカスタマイズ」をご参照ください。

• プラグイン：ユーザーがページにアクセスしたときや、コンテナーがリクエストを受信したときなど、特定のタイミングで特定の操作（例：イベントトラッキングデータの記録、応答データの変更）を実行する必要がある場合、プラグインを開発する必要があります。プラグイン内で対応するイベントをサブスクライブした後、ハンドラーでイベントが運ぶデータを処理できます。プラグインのカスタマイズ方法については、「プラグインのカスタマイズ」をご参照ください。

4. オフラインパッケージの読み込み

従来のオンライン H5 技術はネットワーク状態に左右されやすく、HTML5 ページのパフォーマンスに悪影響を及ぼす可能性があります。HTML5 ページの読み込みにおけるネットワークの影響を最小限に抑えるために、さまざまなサービスをオフラインパッケージとしてカプセル化・パッケージ化できます。その後、配信プラットフォームを介してクライアントに配信し、クライアントリソースを更新します。詳細については、「オフラインパッケージの概要」および「オフラインパッケージの使用」をご参照ください。

5. H5 コンテナーのイベントトラッキング

HTML5 ページが読み込まれる際、Nebula コンテナーは自動的に読み込みパフォーマンスをモニターし、関連する行動データおよびエラー情報を収集します。詳細については、「H5 コンテナーのイベントトラッキング」をご参照ください。