実装ガイド

Nubrick のエディタで作成された埋め込みエクスペリメントを、アプリ内の特定の場所に埋め込むことができます。

コード側では、エクスペリメントIDまたは任意のカスタムID（IDエイリアス）を設定し、使用できます。場所ごとにカスタムIDを事前に設定しておくことをお勧めします。これにより、コードを編集せずに、Nubrick の管理画面で柔軟にエクスペリメントを変更できます。

基本的な使い方

NubrickSDK.embedding("<EXPERIMENT_ID or EXPERIMENT_ID_ALIAS>")

let view = NubrickSDK.embeddingUIView("<EXPERIMENT_ID or EXPERIMENT_ID_ALIAS>")
self.addSubview(view)

import app.nubrick.nubrick.NubrickSDK

NubrickSDK.Embedding("<EXPERIMENT_ID or EXPERIMENT_ID_ALIAS>")

<app.nubrick.nubrick.view.NubrickEmbeddingView
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:nubrickExperimentId="EXPERIMENT_ID_OR_EXPERIMENT_ID_ALIAS" />

import 'package:nubrick_flutter/embedding.dart';

NubrickEmbedding("<EXPERIMENT_ID or EXPERIMENT_ID_ALIAS>")

埋め込みコンポーネントのサイズ

埋め込みコンポーネントのサイズは、次の2種類の指定方法があります

1. アプリ側で指定する

アプリ内で明示的にサイズを指定することで、親レイアウトとの整合が取りやすく、エディタ側での高さ未指定によるレイアウト崩れなど、意図しない挙動を防ぐことができます。高さの異なるコンテンツを配信するユースケースがない場合は、こちらの方法を推奨しております。

NubrickSDK.embedding("<EXPERIMENT_ID or EXPERIMENT_ID_ALIAS>")
    .frame(height: 200)

let view = NubrickSDK.embeddingUIView("<EXPERIMENT_ID or EXPERIMENT_ID_ALIAS>")
view.frame = CGRect(x: 0, y: 0, width: 200, height: 200)
self.addSubview(view)

import app.nubrick.nubrick.NubrickSDK

NubrickSDK.Embedding(
    "<EXPERIMENT_ID or EXPERIMENT_ID_ALIAS>",
    modifier = Modifier.height(200f.dp),
)

<app.nubrick.nubrick.view.NubrickEmbeddingView
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="200dp"
    app:nubrickExperimentId="EXPERIMENT_ID_OR_EXPERIMENT_ID_ALIAS" />

import 'package:nubrick_flutter/embedding.dart';

NubrickEmbedding("<EXPERIMENT_ID or EXPERIMENT_ID_ALIAS>", height: 200)

2. エディタ側で指定する

アプリ側の変更なしで、異なるサイズの施策を配信したり、A/Bテストを実施することが可能です。

エディタ上で該当のframeを選択した状態で、右のパネルからframeのサイズを変更できます。

⚠️ 高さの指定ミスに注意

アプリ側でもエディタ側でもサイズが指定されていない場合、親ビューの制約に従う（fill） 挙動になります。

親がサイズを持っている場合は、その領域いっぱいに表示されます
親が軸方向に無制限な場合（VStack / Column / スクロール内など）は、高さが潰れる・レイアウトが崩れることがあります

また、アプリ側とエディタ側で異なる数値が指定されている場合も、予期しない表示となるおそれがあるため、ご注意ください。

埋め込みコンポーネントのサイズを取得する

onSizeChange を使うと、埋め込みコンポーネントの実サイズ（fill / fixed）を受け取れます。このコールバックは、実際の埋め込みページが表示されたときだけ呼ばれます。読み込み中や not found の状態では呼ばれません。

fill は固定サイズを適用しない（親ビューの制約に従う）ことを表します。

NubrickSDK.embedding(
    "<EXPERIMENT_ID>",
    onSizeChange: { width, height in
        print(width, height)
    }
)

let view = NubrickSDK.embeddingUIView(
    "<EXPERIMENT_ID>",
    onSizeChange: { width, height in
        print(width, height)
    }
)

NubrickSDK.Embedding(
    "<EXPERIMENT_ID> or <EXPERIMENT_CUSTOM_ID>",
    onSizeChange = { width, height ->
        println("width=$width, height=$height")
    }
)

NubrickEmbeddingView embeddingView = findViewById(R.id.nubrick_embedding);
embeddingView.setOnSizeChangeListener((width, height) -> {
    System.out.println("width=" + width + ", height=" + height);
});

イベントハンドラーの追加

埋め込みタイプのエクスペリメントに、イベントハンドラーを追加することができます。

NubrickSDK.embedding("<EXPERIMENT_ID>", onEvent: { event in
    print(event)
})
.frame(height: 200)

let view = NubrickSDK.embeddingUIView("<EXPERIMENT_ID>", onEvent: { event in
    print(event)
})

import app.nubrick.nubrick.NubrickSDK

NubrickSDK.Embedding(
    "<EXPERIMENT_ID> or <EXPERIMENT_CUSTOM_ID>",
    onEvent = { event ->
        println("Event: ${event.name}, deepLink: ${event.deepLink}")
    }
)

XML で NubrickEmbeddingView に ID を設定し、Java でイベントリスナーを登録します。

<app.nubrick.nubrick.view.NubrickEmbeddingView
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/nubrick_embedding"
    android:layout_width="match_parent"
    android:layout_height="200dp"
    app:nubrickExperimentId="EXPERIMENT_ID_OR_EXPERIMENT_ID_ALIAS" />

import app.nubrick.nubrick.view.NubrickEmbeddingView;

NubrickEmbeddingView embeddingView = findViewById(R.id.nubrick_embedding);
embeddingView.setOnEventListener(event -> {
    System.out.println(
        "Event: " + event.getName() + ", deepLink: " + event.getDeepLink()
    );
});

NubrickEmbedding(
  "<EXPERIMENT_ID> or <EXPERIMENT_ID_ALIAS>",
  height: 200,
  onEvent: (event) {
    print("Nubrick Embedding Event: ${event.payload}");
  },
),

ローディング状態のカスタマイズ

読み込み中、失敗、完了の各フェーズでビューをカスタマイズできます。

SwiftUIEmbeddingPhase を使って各フェーズをハンドリングします。

NubrickSDK.embedding("<EXPERIMENT_ID>", onEvent: nil) { phase in
    switch phase {
    case .loading:
        Text("loading")
    case .notFound:
        Text("not found")
    case .failed:
        Text("error")
    case .completed(let view):
        view.frame(height: 200)
    }
}

UIKitEmbeddingPhase を使って各フェーズをハンドリングします。

let view = NubrickSDK.embeddingUIView("<EXPERIMENT_ID>", onEvent: nil) { phase in
    switch phase {
    case .loading:
        return UIActivityIndicatorView()
    case .notFound:
        return UILabel()
    case .failed:
        return UILabel()
    case .completed(let component):
        return component
    }
}

content パラメータを使って EmbeddingLoadingState をハンドリングします。

import app.nubrick.nubrick.NubrickSDK
import app.nubrick.nubrick.component.EmbeddingLoadingState

NubrickSDK.Embedding("<EXPERIMENT_ID> or <EXPERIMENT_CUSTOM_ID>") { state ->
    when (state) {
        is EmbeddingLoadingState.Loading -> CircularProgressIndicator()
        is EmbeddingLoadingState.Completed -> state.view()
        is EmbeddingLoadingState.NotFound -> Text("Not found")
        is EmbeddingLoadingState.Failed -> Text("Error")
    }
}

NubrickEmbeddingView は読み込み状態を内部で処理し、読み込みが完了した埋め込みコンポーネントを表示します。読み込み状態ごとのビューをカスタマイズする場合は、アプリモジュールで Kotlin/Jetpack Compose を有効にし、埋め込み部分だけを NubrickSDK.Embedding(...) で実装して、ComposeView を介して既存の XML レイアウトに組み込んでください。

builder を使って各フェーズをハンドリングします。

NubrickEmbedding(
  "<EXPERIMENT_ID> or <EXPERIMENT_ID_ALIAS>",
  builder: (context, phase, child) {
    case ExperimentPhase.loading:
      return const SizedBox(height: 200, child: Center(child: CircularProgressIndicator()));
    case ExperimentPhase.completed:
      return const SizedBox(height: 200, child: child);
    case ExperimentPhase.notFound:
      return const SizedBox(height: 200, child: Center(child: Text("Experiment not found.")));
    default:
      return const SizedBox.shrink();
  },
),

引数の渡し方

arguments としてパラメータを渡すと、コンポーネント内で展開される動的な変数として利用することができます。

NubrickSDK.embedding(
    "<EXPERIMENT_ID>",
    arguments: ["item_id": itemId]
)
.frame(height: 200)

let view = NubrickSDK.embeddingUIView(
    "<EXPERIMENT_ID>",
    arguments: ["item_id": itemId]
)

作成後に arguments を更新する場合は、返された UIView を NubrickEmbeddingUpdatable にキャストして update(arguments:) を呼び出します。

(view as? NubrickEmbeddingUpdatable)?.update(arguments: ["item_id": itemId])

import app.nubrick.nubrick.NubrickSDK

NubrickSDK.Embedding(
    "<EXPERIMENT_ID> or <EXPERIMENT_CUSTOM_ID>",
    arguments = mapOf("item_id" to itemId)
)

XML で ID を設定した NubrickEmbeddingView に、Java から arguments を渡します。

import app.nubrick.nubrick.view.NubrickEmbeddingView;

import java.util.Collections;

NubrickEmbeddingView embeddingView = findViewById(R.id.nubrick_embedding);
embeddingView.setArguments(
    Collections.singletonMap("item_id", itemId)
);

NubrickEmbedding(
  "<EXPERIMENT_ID> or <EXPERIMENT_ID_ALIAS>",
  height: 200,
  arguments: {
    'item_id': itemId,
  },
),

Previousアプリ内埋め込み (Embeddable Experiment)NextエイリアスID（Alias ID）活用ガイド

Last updated 19 days ago