Web SDK: Auxiaコンソールで見た目を管理する

​

前提条件

• Auxiaコンソールで発行された APIキー と プロジェクトID。
• Auxiaコンソールのプロジェクト設定で Project Website URL が設定されていること。コンソールはこのURLを使ってサイトを開き、表示位置の選択やトリートメントのプレビューを行います。

​

1. 読み込み

<script src="https://auxia.net/interactions/v1/interactions.js"></script>

​

2. 初期化

<script>
  Auxia.initialize({
    apiKey: "YOUR_API_KEY",
    projectId: "YOUR_PROJECT_ID",
    userId: "user-123"
  });
</script>

​

3. コンソールでの見た目の管理を有効化する

​

4. サーフェスとトリートメントを設定する

1. サーフェスを作成し、公開中のサイト上で要素を選択して表示場所を指定します。
2. 対象とするページと、その要素に対する挿入方法を選択します。
3. サーフェスのLayoutを選択します。
4. トリートメントを設定し、公開前にサイト上でプレビューします。

​

ページパス

​

挿入位置

​

Google タグ マネージャーを使う

<script>
  (function () {
    var s = document.createElement("script");
    s.src = "https://auxia.net/interactions/v1/interactions.js";
    s.onload = function () {
      Auxia.initialize({
        apiKey: "YOUR_API_KEY",
        projectId: "YOUR_PROJECT_ID",
        userId: "{{Auxia User ID}}"
      });
    };
    document.head.appendChild(s);
  })();
</script>

​

サイト上でのSDKの動作

• Auxiaからサーフェスの設定を読み込み、ブラウザにキャッシュします。
• 各ページで、ページパスが一致するサーフェスにのみトリートメントを表示します。遅れて読み込まれる要素も待機します。
• 表示・クリック・閉じる操作は自動的に記録されます。インタラクションの記録を参照してください。
• シングルページアプリケーションの画面遷移にも対応しており、パスの変化に合わせてサーフェスを除去・再表示します。
• エラーは内部で処理されます。問題が起きてもページは変更されず、サイトのコードに例外が投げられることも、初回描画が妨げられることもありません。

​

インタラクションの記録

<button data-aux-button-name="cta" data-aux-button-interaction="CLICKED">詳しく見る</button>
<button data-aux-button-name="close" data-aux-button-interaction="DISMISSED">閉じる</button>

​

ページからコンテキスト属性を渡す

<script>
  const auxia = Auxia.initialize({
    apiKey: "YOUR_API_KEY",
    projectId: "YOUR_PROJECT_ID",
    userId: "user-123",
    contextualAttributes: { membership_tier: "gold" }
  });

  // ページスコープ：URLのパスが変わるとクリアされます。
  loadCart().then((cart) => {
    auxia.setContextualAttributes({ cart_value: cart.total }, { scope: "page" });
  });

  // null を指定するとキーが削除されます。
  function onMembershipCancelled() {
    auxia.setContextualAttributes({ membership_tier: null });
  }
</script>

• ページ読み込み時に分かっている値は initialize({ contextualAttributes }) に渡します。最初のリクエストから送信されます。
• setContextualAttributes(attributes, { scope }) は設定済みの値にマージされ、null を指定するとキーが削除されます。呼び出し自体はリクエストを送信しません。値はSDKの次のリクエストで送信されるか、その属性の変化で再取得するよう設定された設置場所ではすぐに送信されます。
• 値には string、number、boolean、Date のいずれかを指定できます。
• scope が意味を持つのは、シングルページアプリケーションの場合だけです。ページを再読み込みすると、すべての値がクリアされます（SDKが初期状態から始まります）。"page" の場合はURLのパスが変わったときにもクリアされ、"session"（デフォルト）の場合は画面遷移しても保持されます。
• 空のキーやAuxiaが予約しているキー（auxia_* で始まるキー、user_id、surfaces など）、サポートされていない型の値、不明な scope を指定すると例外をスローします。NaN、Infinity、無効な Date は、ブラウザのコンソールにエラーを出力してスキップされます。

​

属性の変化で設置場所を再取得する

• 空なら埋める（デフォルト）：設置場所に何も表示されていない間だけ再取得します。すでにページに表示されているコンテンツはそのままです。
• コンテンツを置き換え：値が変わるたびに再取得し、新しい結果を表示します。何も返ってこなかった場合は、現在のコンテンツがそのまま残ります。

​

スタイリング

/* コンソール上のLayoutテンプレート内 */
.cta { background: var(--brand-primary, #0b5fff); }

​

カスタムコードで管理しているサーフェスをコンソールに移す

• そのサーフェスの fetchAndRenderTreatments() または getTreatments() の呼び出しを削除します。他のサーフェスの呼び出しは引き続き動作します。
• コンテナ要素と surfaceHtmlElementId は、コンソールで選択する表示位置に置き換わります。
• data-aux-* のインタラクション属性は、ページのマークアップではなく、コンソール上のLayoutおよびDesignテンプレートに記述します。
• コンテキスト属性は呼び出しごとに渡さず、setContextualAttributes() で一度設定します。

​

トラブルシューティング

• コンソールに SDK status 列が表示されているか。表示されていない場合、プロジェクトでコンソールでの見た目の管理がまだ有効化されていません。
• Auxia.initialize() が空でない userId で呼び出されているか。
• サーフェスのページパスが、表示中のページと一致しているか。
• サーフェスを配置した要素がページ上に存在するか。
• サーフェスに公開済みのLayoutと、配信中のトリートメントが1つ以上あるか。