> For the complete documentation index, see [llms.txt](https://docs.nubrick.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nubrick.app/other/setproperties.md).

# ユーザー属性情報（setProperties）について

### ユーザー属性設定（setProperties）の概要 <a href="#overview" id="overview"></a>

Nubrickにおける`setProperties`とは、アプリを利用している**ユーザーの属性情報（プロパティ）をNubrick側に連携する機能**です 。

通常、アプリ側で保持している”会員ランク”、”性別”、”年齢”、”契約プラン”などの会員情報をNubrickに連携することで、管理画面から特定のセグメント条件に合致するユーザーにだけ施策を配信することが可能になります 。

### 個人情報に関する連携について <a href="#pii" id="pii"></a>

* 現在のNubrickの仕様では、`setProperties` で設定された値のうち`userId`のみをユーザーの識別のためにサーバーに送信しています
  * そのため、`userId` には**氏名やメールアドレスなどの個人情報は使用しないでください**。
    * 連番など推測されやすい値を使用する場合は、ハッシュ化などによって推測困難な値に変換してから利用してください。IDは第三者から推測困難な値であることを推奨します。
    * ユーザーIDを意味する値をユーザータグで送信する場合は、必ず`userId`という名称で、システム上でユニークなID（1人のユーザーに対して与えられ、システム上で重複しない）を文字列形式で送信してください。
  * `userId` 以外の値はサーバーに連携されていませんが、単体で個人を特定できるような個人情報は設定しないことを推奨しています

### setPropertiesの仕様 <a href="#spec" id="spec"></a>

プロパティとして設定できるデータの形式、キーの制限と命名、あらかじめ用意されている自動取得項目について説明します。

#### 1. サポートされているデータ型

以下の5種類のデータ型をプロパティの値として設定できます 。

* **String**（文字列）: 例 "Gold", "Tokyo"
* **Bool**（真偽値）: 例 true, false
* **Int**（整数）: 例 25, 100
* **Double**（浮動小数点数）: 例 4.5
* **Date**（日付）

※ `Date` は iOS でサポートされます。

#### 2. プロパティキーの制限と命名規則

`setProperties` のキーは、配信対象のフィルタと、エディタ上の変数（`{{ user.plan }}` など）から同じ名前で参照されます。iOS / Android / Flutter では `Dictionary` / `Map` の object key として扱うため、次の制限と命名を守ってください。

{% hint style="warning" %}
キーに使える文字は、**半角英数字（`a-z`, `A-Z`, `0-9`）**、**アンダースコア（`_`）**、**ハイフン（`-`）** のみです。日本語・全角文字・スペース、および `.` `/` `:` などの記号は使用できません。
{% endhint %}

* `.` は変数パスの区切り（`{{ user.plan }}`）として予約されているため、キー自体には含めないでください
* キーは大文字・小文字を区別します（`plan` と `Plan` は別キーです）

**推奨する命名規則（camelCase）**

モバイルの object key の慣例（Swift の `Dictionary` / `Codable`、Kotlin の `Map` / data class、Dart の `Map`）に合わせ、**camelCase** を推奨します。Nubrick のビルトインプロパティ（`userId`, `languageCode`, `osVersion` など）もこの形式です。

| ルール                      | 良い例                                   | 避ける例                                  |
| ------------------------ | ------------------------------------- | ------------------------------------- |
| camelCase で書く            | `plan`, `membershipPlan`, `isPremium` | `membership_plan`, `membership-plan`  |
| 先頭は英字にする                 | `isTwoFactorEnabled`                  | `2faEnabled`                          |
| Bool は `is` / `has` で始める | `isPremium`, `hasCompletedOnboarding` | `premiumFlag`                         |
| 日本語・スペース・記号を使わない         | `prefecture`                          | `会員ランク`, `user type`, `user.plan`     |
| ビルトインキーを上書きしない           | （カスタム名を使う）                            | `languageCode` や `osVersion` を独自用途で使う |

* `userId` だけは、カスタムのユーザー識別子を設定する目的で上書きして構いません（個人情報は使わないでください）
* `_` と `-` は仕様上使えますが、ハイフンは Swift / Kotlin / Dart の identifier にできないため、単語の区切りには camelCase を使ってください（`snake_case` / kebab-case は非推奨）

#### 3. ビルトイン・プロパティ（自動取得項目）

SDKを導入すると、以下の項目はデフォルトで自動的に設定~~収集~~されています。これらを別途手動で設定する必要はありません 。

| **キー名**                | **内容**                                              |
| ---------------------- | --------------------------------------------------- |
| `userId`               | ユーザーID（デフォルトはUUID形式）                                |
| `languageCode`         | 言語設定（例: ja, en）                                     |
| `regionCode`           | 地域設定（例: JP, US）                                     |
| `sdkVersion`           | Nubrick SDK のバージョン                                  |
| `osName` / `osVersion` | OS名およびOSバージョン                                       |
| `appId`                | アプリID（iOS: Bundle Identifier、Android: Package Name） |
| `appVersion`           | アプリのバージョン                                           |
| `cfBundleVersion`      | iOS の `CFBundleVersion`                             |

### 実装例 <a href="#examples" id="examples"></a>

{% tabs %}
{% tab title="iOS" %}

```swift
NubrickSDK.setUserProperties([
    "plan": "gold",
    "prefecture": "Tokyo"
])

NubrickSDK.setUserId("<CUSTOM_USER_ID>")

let userId = NubrickSDK.getUserId()
let properties = NubrickSDK.getUserProperties()
print(userId ?? "")
print(properties)
```

{% endtab %}

{% tab title="Android (Kotlin)" %}

```kotlin
NubrickSDK.setUserProperties(
    mapOf(
        "plan" to "gold",
        "prefecture" to "Tokyo"
    )
)

NubrickSDK.setUserId("<CUSTOM_USER_ID>")

val userId = NubrickSDK.getUserId()
val properties = NubrickSDK.getUserProperties()
println(userId)
println(properties)
```

{% endtab %}

{% tab title="Android (Java)" %}

```java
import java.util.HashMap;
import java.util.Map;

Map<String, Object> properties = new HashMap<>();
properties.put("plan", "gold");
properties.put("prefecture", "Tokyo");
NubrickSDK.setUserProperties(properties);

NubrickSDK.setUserId("<CUSTOM_USER_ID>");

String userId = NubrickSDK.getUserId();
Map<String, String> currentProperties = NubrickSDK.getUserProperties();
System.out.println(userId);
System.out.println(currentProperties);
```

{% endtab %}

{% tab title="Flutter" %}

```dart
final user = NubrickUser();
await user.setProperties({
  'plan': 'gold',
  'prefecture': 'Tokyo',
  'userId': '<CUSTOM_USER_ID>',
});

final userId = await user.getId();
final properties = await user.getProperties();
print(userId);
print(properties);
```

{% endtab %}
{% endtabs %}

### 実装時の注意事項 <a href="#notes" id="notes"></a>

エンジニアによる実装および運用にあたって、以下の点に注意してください。

* **プライバシーへの配慮**
  * 設定された`userId`は上記記載の通りユーザー識別のためにサーバーへ送信されます。そのため、ユーザーIDとして**個人を特定できる直接的な情報や、プライバシーに関わる機密データ**を設定することは推奨されません 。
* **データ連携のタイミング**
  * `setProperties`で設定された値は、即座にそのユーザーの属性として更新されます。ユーザーの状態が変化したタイミング（例：ログイン後、プロフィール更新後）で呼び出すように実装してください 。
* **デバッグ機能の活用**
  * 実装したプロパティが正しく反映されているかは、`NubrickSDK.getUserProperties()`メソッドを呼び出すことで確認できます 。

### 主なユースケース <a href="#usecases" id="usecases"></a>

`setProperties`を活用することで、以下のような高度なマーケティング施策が実現できます。

#### 1. ユーザーセグメントによる配信ターゲットの絞り込み

特定の属性を持つユーザーをフィルタリングして、キャンペーンやA/Bテストを表示できます 。

* **例**: 「ゴールド会員」のユーザーだけに、先行セール案内をアプリ内メッセージで表示する。
* **例**: 「最終購入日から30日以上経過している」ユーザーだけに、再訪問クーポンを配布する。

#### 2. コンテンツ内での動的な変数表示

連携したプロパティを、配信するUI（バナーやメッセージ）内の変数として利用できます 。

* **例**: メッセージ内に「現在契約中のプランは○○です」といった、ユーザーごとの情報を動的に差し込む。

#### 3. パーソナライズされたレコメンドの提供

ユーザーの行動特性や属性に基づいた体験を提供し、エンゲージメントを高めます 。

* **例**: 「興味カテゴリー：キャンプ」と設定されているユーザーのホーム画面に、アウトドア関連の特集バナーを優先的に表示する。
