データ連携(リアルタイム取り込み)導入手順

スタートアップガイド

  • 本記事ではデータ連携タグ(リアルタイム取り込み)の導入手順を説明します。
  • 本記事の手順を実施頂くことで、データ連携タグがサイト内で動作するようになります。
  • Sprocket タグを既に導入していることを前提とします。

目次

  1. データ連携タグの動作
  2. サイトへのタグ埋め込み
  3. エラーチェック

1. データ連携タグの動作

このセクションではデータ連携タグの挙動を説明します。
本資料では[ユーザー連携タグ]を例にとって説明を行いますが、他のタグの場合も基本的な動作は同じです。

データ送信

1.Sprocket タグが埋め込まれているページを開いた上で、ブラウザの開発者ツールのコンソールでSprocket Developer Hub ユーザー属性タグに記載されている[ユーザー属性タグ]のサンプルコードを実行します。

(function() {
  var props = {
    userId: '123456',
    point: 200,
    group: 'VIP',
    purchase: {
      initialDate: '2019-01-01T12:00:00+09:00',
      totalCount: 10
    }
  };
  console.log('Sprocket: User props:\n' + JSON.stringify(props, null, '  '));
  SPSDK.user(props);
})();

2.コードを実行するとユーザーに関する上記のデータ属性が Sprocket プラットフォームに送信されます。このとき、引数に与えたデータが下記のようにコンソールに表示されます。

Sprocket: User props:
{
  "userId": "123456",
  "point": 200,
  "group": "VIP",
  "purchase": {
    "initialDate": "2019-01-01T12:00:00+09:00",
    "totalCount": 10
  }
}

以上がデータ送信時が正常に完了した場合の挙動です。
スクリプトの実行後にエラーメッセージが表示されなければ送信は成功しています。

送信エラー

バリデーション仕様で禁止されている引数を渡した場合はエラーが発生します。
実際にエラーが発生するような引数を与えて挙動を確認します。

1.Sprocket Developer Hub ユーザー属性タグのサンプルコードに不正な引数を与えた下記のスクリプトをブラウザの開発者ツールのコンソールから実行します。

// 送信に失敗するスクリプト
(function() {
  var props = {
    userId: '123456',
    point: '200', // 数値型であるべきプロパティが文字列型になっている。
    group: 'VIP',
    purchase: {
      initialDate: '2019-01-01T12:00:00+09:00',
      totalCount: 10
    }
  };
  console.log('Sprocket: User props:\n' + JSON.stringify(props, null, '  '));
  SPSDK.user(props);
})();

2.この場合はコンソールに次のようにエラーメッセージが表示されます。

Sprocket: User props:
{
  "userId": "123456",
  "point": "200",
  "group": "VIP",
  "purchase": {
    "initialDate": "2019-01-01T12:00:00+09:00",
    "totalCount": 10
  }
}

sprocket-jssdk.js:55 ValidationError: point type or format is invalid.

このようにバリデーションエラーが発生します。
エラーが発生した場合データは送信されません。

以上がデータ連携タグの基本的な動作です。

📘

エラーの原因

エラーが発生するケースとしては、引数のValueの型が期待したものと異なっている、必須プロパティが足りないなどがあります。詳しい仕様はSprocket Developer Hub ユーザー属性タグをご覧ください。

📘

連携したデータの反映タイミングについて

データ連携(リアルタイム取り込み)タグで連携されるデータは、タグが発火したページの次のページ(もしくは数ページ遷移後)に、シナリオのセグメント条件にご利用いただけるようになります。これは、データ連携タグが発火したタイミングでデータの連携(送信)を実行するためです。

2. サイトへのタグ埋め込み

サイトへデータ連携タグを埋め込むことで、データ連携が有効化されます。
タグの埋め込みの際には、各データ連携タグの解説ページを参考に下記の作業を行ってください。

📘

ツールを使ってデータ連携タグを埋め込むには

  • Google タグマネージャでのデータ連携タグ導入手順はこちらをご覧ください。
  • ecbeing, futureshopなどのECプラットフォームではデータ連携タグの導入をサポートしています。詳しくはデータ連携(ECサイト)をご確認ください。
  1. Sprocket Developer Hub ユーザー属性タグなどに例示されているデータ連携タグを、タグマネージャなどを使ってデータを取得したい Web ページに出力してください。
  2. 各データ連携タグの解説ページに掲載されているサンプルコードを参考に、送信したいデータ項目が JavaScript 変数に吐き出されるようにカスタマイズを行ってください。
  3. カスタマイズが終わったらコンソールを確認します。「1.データ連携タグの動作」で確認したログが表示されていればタグが埋め込めています。

🚧

注意事項

必ず Sprocket タグの読み込みより後にデータ連携タグが実行されるように実装してください。Sprocket タグの読み込みが完了していない状態でデータ連携を実行した場合、データが送信されません。タグマネージャなどで非同期に Sprocket タグを読み込んでいる場合は特にご注意ください。

3. エラーチェック

データ連携タグの導入が完了したら、最後にエラーチェックを行います。

データ連携タグの実行時に「コンソールにログが出力され、エラーメッセージが出ない」状態になっていればデータ連携が正常に動作しています。この動作になりましたらデータ連携タグの導入は完了です。

上記の動作にならない時は実装に不備がありますので、下記を確認してください。

❗️

コンソールにエラーが出る場合

コンソールにエラーが出るようであれば何らかの不正な形式のデータが引数に含まれています。(「1.ユーザー属性タグの動作確認」を参照ください。)
Sprocket Developer Hub [ユーザー属性タグ]のバリデーション仕様とコンソールのエラーメッセージを比較し、引数の形式を修正してください。

❗️

ログが出力されない場合

データ連携タグが実行されていません。(データ連携タグが実行されていれば、エラーの場合でも引数の情報はコンソールに出力されます)
タグが出力されていない、Sprocket タグが入っていないなどが原因として考えられます。

🚧

バリデーション仕様(全タグ共通)

以下に該当する場合、エラーとなり全てのプロパティが送信されません。

  • フィールド名(Key)が不適切な場合

    • データ項目定義に存在しないフィールド名がある
  • 値(Value)が不適切な場合

    • 文字列(「ISO8601拡張形式」、「ISO8601拡張形式、日付のみ」を含む)/数値/論理型のデータ型が異なる(エラーの例: totalAmount: "1" ※数値型を期待しているが、文字列が出力されている)
      なお以下のケースでは Sprocket がキャスト処理を行うことによりデータが送信されます。(救済措置)

      文字列型の項目に数値型が入力された場合
      文字列型にキャストしてデータが送られます。
      ※ ただし、値(Value)が空文字列の場合は、フィールド名(Key)が無いものとして扱うためデータは送られません。

      数値型の項目に文字列型が入力された場合
      数値型にキャストした後、文字列型に戻して値が一致する場合のみ、数値型でデータが送られます。
      ※ ただし、値(Value)が空文字列の場合は、キャスト処理が行われずエラーとなるため、データは送られません。

      ブーリアンの項目に文字列型が入力された場合
      文字列で「true」、「false」と一致する場合は、ブーリアンとして解釈し、データが送られます。

    • 文字列(ISO8601拡張形式) の形式エラー

    • 文字列(ISO8601拡張形式、日付のみ) の形式エラー(エラーの例: birthday: '2019-01-01T12:00:00+09:00' ※時刻が含まれている)

    • 値に null が含まれる

    • 文字列長が64文字より大きい(ただし、 ユーザー属性タグuserId を除く。ユーザー属性タグuserId のバリデーション仕様は補足説明を参照してください)