> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auxia.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Web SDK: カスタムコードで見た目を管理する
> Auxia Web SDKでトリートメントを取得し、getTreatments または fetchAndRenderTreatments を使ってカスタムコードで描画します。
日本語版はAIによる翻訳です。正確な情報については[英語版](/api-reference/sdk/render-from-your-code)をご参照ください。
サイト上の見た目を細かく制御したい場合は、こちらの方法で行います。トリートメントの表示場所、必要に応じて描画方法も、ページ側のカスタムコードで実装します。
ほとんどのサーフェスでは不要です。[Auxiaコンソールで見た目を管理する](/ja/api-reference/sdk/javascript-sdk)では、サイト側のコードは `Auxia.initialize()` のみです。どちらの方式も同じスクリプトを使用し、同じプロジェクト内でサーフェスごとに併用できます。
***
## 目次
1. [クイックスタート](#quick-start)
2. [インストール](#installation)
3. [初期化](#initialization)
4. [SDKメソッドの概要](#sdk-methods-overview)
5. [メソッド1: fetchAndRenderTreatments](#method-1-fetchandrendertreatments)
6. [メソッド2: getTreatments](#method-2-gettreatments)
7. [コンテキスト属性](#contextual-attributes)
8. [完全な例](#complete-examples)
9. [エラーハンドリング](#error-handling)
***
クイックスタート
Auxiaのトリートメントをページにレンダリングするための最小限の例です。各部分の詳細は、以降のセクションで説明します。
```html theme={null}
```
> **注意:** 上記のコードが見慣れなくても心配ありません。インストール、初期化、SDKメソッドの各コンポーネントは、以降のセクションでステップごとに説明します。
***
インストール
HTMLページにAuxia SDKスクリプトを追加します:
```html theme={null}
```
このスクリプトにより、サービスの初期化と操作に使用するグローバルな`Auxia`オブジェクトが公開されます。
### 前提条件
統合する前に、以下をご用意ください:
* Auxiaから提供された**APIキー**
* AuxiaコンソールからのプロジェクトID（**Project ID**）
* Auxiaコンソールで設定された**サーフェス**（例: "HOME\_PAGE"、"CHECKOUT\_BANNER"）
***
初期化
SDKメソッドを呼び出す前に、認証情報を用いて初期化する必要があります:
```javascript theme={null}
const auxia = Auxia.initialize({
apiKey: "YOUR_API_KEY",
projectId: "YOUR_PROJECT_ID",
userId: "user@example.com"
});
```
### 設定オプション
| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | AuxiaのAPIキー |
| `projectId` | string | Yes | AuxiaのプロジェクトID |
| `userId` | string | No | 現在のユーザーの識別子（後から設定可能） |
### ユーザーIDの更新
初期化時にユーザーIDが利用できない場合（例: ページ読み込み後にユーザーがログインする場合）、後から更新できます:
```javascript theme={null}
auxia.updateUserId("logged-in-user@example.com");
```
***
SDKメソッドの概要
Auxia SDKには、トリートメントを取得するための**2つのメソッド**が用意されています:
| Method | Description | Use When |
| - | - | - |
| `fetchAndRenderTreatments()` | トリートメントを取得し、指定されたDOM要素に自動的にレンダリングします | Auxiaにトリートメントの取得と表示の両方を任せたい場合 |
| `getTreatments()` | トリートメントのみを取得し、データを返します | カスタムレンダリングロジックが必要な場合や、トリートメントの表示方法を完全に制御したい場合 |
両方のメソッドは類似のパラメータを受け付けます。主な違いは、`fetchAndRenderTreatments()`では各トリートメントのレンダリング先を指定する必要がありますが、`getTreatments()`は単にトリートメントデータを返すだけという点です。
***
メソッド1: fetchAndRenderTreatments
SDKにAuxiaからトリートメントを取得し、ページに自動的にレンダリングさせたい場合にこのメソッドを使用します。このメソッドは`Promise`を返します。トリートメントはDOMに直接レンダリングされます。
**レンダラー設定**
Auxiaは各サーフェスのレンダラーを設定します。サーフェスのレンダラーの設定や変更については、Auxiaの担当者にお問い合わせください。
**自動インタラクションログ**
`fetchAndRenderTreatments`を使用すると、SDKがトリートメントの表示、クリック、非表示に対する`logTreatmentInteraction`呼び出しを自動的に処理します。
### 基本的な使い方
```javascript theme={null}
auxia.fetchAndRenderTreatments({
surfaceRequests: [
{
surfaceName: "HOME_PAGE",
surfaceHtmlElementId: "banner-container",
minimumTreatmentCount: 1,
maximumTreatmentCount: 5
}
],
languageCode: "en"
});
```
### リクエストパラメータ
| Parameter | Type | Required | Description |
| - | - | - | - |
| `surfaceRequests` | array | Yes | サーフェスリクエストオブジェクトの配列（以下を参照） |
| `languageCode` | string | Yes | トリートメントコンテンツの言語コード（例: "en"、"ja"、"ko"） |
| `contextualAttributes` | array | No | パーソナライゼーションのための追加コンテキスト（[コンテキスト属性](#contextual-attributes)を参照） |
### サーフェスリクエストパラメータ
`surfaceRequests`配列内の各オブジェクトには以下を含める必要があります:
| Parameter | Type | Required | Description |
| - | - | - | - |
| `surfaceName` | string | Yes | Auxiaコンソールで設定されたサーフェス名 |
| `surfaceHtmlElementId` | string | Yes | トリートメントをレンダリングするDOM要素のID |
| `minimumTreatmentCount` | number | Yes | 返すトリートメントの最小数（トリートメントがオプションの場合は0を使用） |
| `maximumTreatmentCount` | number | Yes | 返すトリートメントの最大数（1以上である必要があります） |
> **注意:** ポップアップやモーダルとして設定されたサーフェスの場合、`surfaceHtmlElementId`にはプレースホルダーの値（例: `"popup-surface"`）を使用できます。SDKが新しいDOM要素を作成し、既存のコンテンツの上にレンダリングするためです。サーフェスのポップアップまたはモーダルレンダラーの設定については、Auxiaの担当者にお問い合わせください。
### HTMLの設定
ページには、`surfaceHtmlElementId`の値と一致するIDを持つコンテナ要素が必要です:
```html theme={null}
```
### 複数サーフェスの取得
1回の呼び出しで複数のサーフェスのトリートメントをリクエストできます:
```javascript theme={null}
auxia.fetchAndRenderTreatments({
surfaceRequests: [
{
surfaceName: "HEADER_BANNER",
surfaceHtmlElementId: "header-banner",
minimumTreatmentCount: 0,
maximumTreatmentCount: 1
},
{
surfaceName: "PRODUCT_RECOMMENDATIONS",
surfaceHtmlElementId: "product-recs",
minimumTreatmentCount: 3,
maximumTreatmentCount: 6
},
{
surfaceName: "FOOTER_PROMO",
surfaceHtmlElementId: "footer-promo",
minimumTreatmentCount: 0,
maximumTreatmentCount: 2
}
],
languageCode: "en"
});
```
対応するHTML:
```html theme={null}
```
### コンテキスト属性の追加
パーソナライゼーションを向上させるために追加のコンテキストを渡すことができます:
```javascript theme={null}
auxia.fetchAndRenderTreatments({
surfaceRequests: [
{
surfaceName: "HOME_PAGE",
surfaceHtmlElementId: "promo-banner",
minimumTreatmentCount: 1,
maximumTreatmentCount: 1
}
],
languageCode: "en",
contextualAttributes: [
{ key: "userSegment", stringValue: "premium" },
{ key: "cartItemCount", integerValue: 3 },
{ key: "isLoggedIn", boolValue: true }
]
});
```
サポートされるすべての属性タイプについては、[コンテキスト属性](#contextual-attributes)を参照してください。
### fetchAndRenderTreatmentsの完全な例
```html theme={null}
My App
Welcome
```
***
メソッド2: getTreatments
トリートメントのレンダリング方法を完全に制御したい場合にこのメソッドを使用します。SDKはトリートメントを取得してデータとして返すため、独自のUIを構築できます。
**手動インタラクションログが必要**
`getTreatments`を使用する場合、トリートメントの表示、クリック、非表示を追跡するために`logTreatmentInteraction`を呼び出す責任があります。詳細は[Log Treatment Interactions](/ja/api-reference/log-treatment-interactions)を参照してください。
### 基本的な使い方
```javascript theme={null}
auxia.getTreatments({
surfaceRequests: [
{
surfaceName: "HOME_PAGE",
minimumTreatmentCount: 1,
maximumTreatmentCount: 5
}
],
languageCode: "en"
}).then((response) => {
console.log(response.treatments);
});
```
### リクエストパラメータ
| Parameter | Type | Required | Description |
| - | - | - | - |
| `surfaceRequests` | array | Yes | サーフェスリクエストオブジェクトの配列（以下を参照） |
| `languageCode` | string | Yes | トリートメントコンテンツの言語コード |
| `contextualAttributes` | array | No | パーソナライゼーションのための追加コンテキスト |
### サーフェスリクエストパラメータ
| Parameter | Type | Required | Description |
| - | - | - | - |
| `surfaceName` | string | Yes | Auxiaコンソールで設定されたサーフェス名 |
| `minimumTreatmentCount` | number | Yes | 返すトリートメントの最小数 |
| `maximumTreatmentCount` | number | Yes | 返すトリートメントの最大数（1以上である必要があります） |
> **注意:** `fetchAndRenderTreatments`とは異なり、レンダリングを自分で行うため、`surfaceHtmlElementId`は不要です。
### レスポンスの構造
このメソッドは以下に解決されるPromiseを返します:
```javascript theme={null}
{
responseId: "uuid-string",
treatments: [
{
treatmentId: "treatment-123",
treatmentTrackingId: "tracking-456",
rank: 1,
contentLanguageCode: "en",
treatmentType: "BANNER",
surface: "HOME_PAGE",
contentFields: [
{ fieldName: "html", value: "...
" },
{ fieldName: "title", value: "Special Offer" },
{ fieldName: "imageUrl", value: "https://..." },
{ fieldName: "ctaText", value: "Learn More" },
{ fieldName: "ctaUrl", value: "https://..." }
]
}
]
}
```
### トリートメントオブジェクトのプロパティ
| Property | Type | Description |
| - | - | - |
| `treatmentId` | string | トリートメントの一意の識別子 |
| `treatmentTrackingId` | string | アナリティクス用のトラッキング識別子 |
| `rank` | number | トリートメントのランキング/位置 |
| `contentLanguageCode` | string | トリートメントコンテンツの言語 |
| `treatmentType` | string | トリートメントの種類（Auxiaコンソールで設定） |
| `surface` | string | トリートメントが属するサーフェス名 |
| `contentFields` | array | コンテンツフィールドオブジェクトの配列 |
### コンテンツフィールド
各トリートメントには`contentFields`が含まれます。これはAuxiaコンソールで設定された名前と値のペアの配列です。一般的なフィールドには以下が含まれます:
| Field Name | Description |
| - | - |
| `html` | レンダリングするHTMLコンテンツ |
| `title` | トリートメントのタイトル |
| `description` | トリートメントの説明 |
| `imageUrl` | 画像のURL |
| `ctaText` | コールトゥアクションボタンのテキスト |
| `ctaUrl` | コールトゥアクションのリンク先URL |
### コンテンツフィールドの操作
```javascript theme={null}
auxia.getTreatments({
surfaceRequests: [
{
surfaceName: "PRODUCT_CARDS",
minimumTreatmentCount: 1,
maximumTreatmentCount: 4
}
],
languageCode: "en"
}).then((response) => {
response.treatments.forEach((treatment) => {
// Get specific fields
const title = treatment.contentFields.find(f => f.fieldName === "title")?.value;
const imageUrl = treatment.contentFields.find(f => f.fieldName === "imageUrl")?.value;
const ctaUrl = treatment.contentFields.find(f => f.fieldName === "ctaUrl")?.value;
console.log(title, imageUrl, ctaUrl);
});
});
```
### カスタムレンダリングの例
```javascript theme={null}
auxia.getTreatments({
surfaceRequests: [
{
surfaceName: "PRODUCT_CARDS",
minimumTreatmentCount: 1,
maximumTreatmentCount: 4
}
],
languageCode: "en",
contextualAttributes: [
{ key: "category", stringValue: "electronics" }
]
}).then((response) => {
const container = document.getElementById("product-grid");
response.treatments.forEach((treatment) => {
const title = treatment.contentFields.find(f => f.fieldName === "title")?.value;
const imageUrl = treatment.contentFields.find(f => f.fieldName === "imageUrl")?.value;
const ctaUrl = treatment.contentFields.find(f => f.fieldName === "ctaUrl")?.value;
const ctaText = treatment.contentFields.find(f => f.fieldName === "ctaText")?.value || "Learn More";
const card = document.createElement("div");
card.className = "product-card";
card.innerHTML = `
${title}
${ctaText}
`;
container.appendChild(card);
const logInteraction = (interactionType) => auxia.logTreatmentInteraction({
treatmentTrackingId: treatment.treatmentTrackingId,
surfaceName: treatment.surface,
treatmentId: treatment.treatmentId,
interactionType
});
logInteraction("VIEWED");
card.querySelector(".cta-button").addEventListener("click", () => logInteraction("CLICKED"));
});
});
```
`getTreatments` を使用する場合、インタラクションの記録はサイト側の責任です。トリートメントが表示されたら `VIEWED`、クリックされたら `CLICKED`、閉じられたら `DISMISSED` を記録してください。
***
コンテキスト属性
コンテキスト属性を使用すると、トリートメントのパーソナライゼーションを向上させるために、ユーザー、セッション、またはページコンテキストに関する追加情報を渡すことができます。
### サポートされる属性タイプ
| Type | Format | Example |
| - | - | - |
| String | `{ key: "...", stringValue: "..." }` | `{ key: "userSegment", stringValue: "premium" }` |
| Integer | `{ key: "...", integerValue: ... }` | `{ key: "cartItemCount", integerValue: 3 }` |
| Double | `{ key: "...", doubleValue: ... }` | `{ key: "accountBalance", doubleValue: 1500.50 }` |
| Boolean | `{ key: "...", boolValue: ... }` | `{ key: "isFirstVisit", boolValue: true }` |
| Timestamp | `{ key: "...", timestampValue: ... }` | `{ key: "lastPurchaseDate", timestampValue: new Date() }` |
| Timestamp (ms) | `{ key: "...", timestampMillisecondsValue: ... }` | `{ key: "sessionStart", timestampMillisecondsValue: Date.now() }` |
### よく使用されるコンテキスト属性
以下は、よく使用されるコンテキスト属性の例です:
| Attribute | Type | Description |
| - | - | - |
| `userSegment` | string | ユーザーのティアまたはセグメント（例: "premium"、"basic"） |
| `pageType` | string | 現在のページタイプ（例: "home"、"product"、"checkout"） |
| `cartValue` | double | 現在のカートの金額 |
| `cartItemCount` | integer | カート内のアイテム数 |
| `isLoggedIn` | boolean | ユーザーが認証済みかどうか |
| `daysSinceLastPurchase` | integer | ユーザーの最後の購入からの日数 |
| `deviceType` | string | デバイスの種類（例: "mobile"、"desktop"） |
| `productCategory` | string | 現在閲覧中の商品カテゴリ |
### 使用例
```javascript theme={null}
auxia.fetchAndRenderTreatments({
surfaceRequests: [
{
surfaceName: "CHECKOUT_UPSELL",
surfaceHtmlElementId: "upsell-container",
minimumTreatmentCount: 1,
maximumTreatmentCount: 3
}
],
languageCode: "en",
contextualAttributes: [
{ key: "userSegment", stringValue: "premium" },
{ key: "cartValue", doubleValue: 150.00 },
{ key: "cartItemCount", integerValue: 3 },
{ key: "isLoggedIn", boolValue: true },
{ key: "productCategory", stringValue: "electronics" }
]
});
```
***
完全な例
```html theme={null}
My Store
Welcome to My Store
```
```html theme={null}
My App
```
```html theme={null}
Product Recommendations
Recommended For You
```
***
エラーハンドリング
エラーハンドリングはAuxia SDKによって管理されています。エラーハンドリングの動作や設定の詳細については、Auxiaの担当者にお問い合わせください。