LINE Conversion API v1 (1.0.0)

開発ガイドライン

Conversion APIにイベントを送信するにあたり, 注意すべき事項やベストプラクティスを記載しています.

イベントの送信順について

イベントの送信では, 可能な限りイベントが発生した順番で送信する必要があります.

イベントが発生した順番でイベントを送信しなかった場合, 本来は先に発生していたコンバージョンが後から発生したように見えたり, 弊社が行う広告配信の最適化において影響が発生したりする可能性があります.

イベントの送信タイミングについて

より正確なコンバージョン計測を行うためには, イベントは発生後なるべく早い時点で送信する必要があります. 弊社によるコンバージョンのレポーティングでは, コンバージョンの発生した時刻には「イベントが実際に弊社に到達した時点での時刻」を利用します.

弊社のWebコンバージョンの有効期限は以下の通りです.

  • デフォルトコンバージョンの場合: 広告クリックから30日
  • カスタムコンバージョンの場合: 1〜180日の間でお客様が設定します

LINE Tag, Conversion APIのいずれでも, この有効期限の判断基準はイベントが実際に弊社に到達した時点での時刻が利用されます. これは例えば, 広告がクリックされた時刻から「30日以内に実際のコンバージョンが発生した」場合でも, 広告クリックから30日経ってから弊社へのイベントの送信を行った場合には, 有効なコンバージョンとして判断されません.

イベントの重複排除について

コンバージョンの重複計測を回避するために, イベントにdeduplication_keyを含める必要があります. 以下の理由などにより, クライアントは同一のイベントを複数回送信する可能性があります.

  • クライアントエラーやConversion API側での一時的な障害, またネットワークエラーなどの理由でConversion APIへの送信が失敗する可能性があります. この場合クライアントは送信をリトライをする必要があります.
  • LINE TagとConversion APIの二つの経路から, 同等の意味を持つイベントをそれぞれ送信することで, LINE Tag経由で計測できなかったデータをConversion API経由からのデータで補完できます. この時, 異なる経路から同じイベントを送信するため, 常に同じイベントが2件以上送信されることになります.
Deduplication Key Flow 2

重複排除対象となるフィールドの組み合わせ

イベントのdeduplication_keyフィールドに, そのイベントを一意に特定するキーを設定することで, イベントの重複排除が可能です. 重複排除の際に, 弊社が同一のイベントとしてみなすものは, event_namededuplication_keyの組み合わせが一致する場合に限ります.

Deduplication Key Flow 1

例えば, 以下の全てのイベントは異なるイベントとして扱われるため, 重複排除の対象となりません.

{
  ...
  "event": {
    "source_type": "web",
    "event_type": "conversion",
    "event_name": "Conversion",
    "deduplication_key": "key1"
  },
  ...
}
{
  ...
  "event": {
    "source_type": "web",
    "event_type": "conversion",
    "event_name": "Conversion",
    "deduplication_key": "key2"
  },
  ...
}
{
  ...
  "event": {
    "source_type": "web",
    "event_type": "conversion",
    "event_name": "Purchase",
    "deduplication_key": "key1"
  },
  ...
}

イベントの重複排除期間

同じevent_nameとdeduplication_keyを持つ複数のイベントが送信された場合, 最初のイベントがConversion APIに到達し, 初めて処理された時点から30日以内に到着するイベントについては重複排除の対象となります.

LINE Tagの設定

LINE TagとConversion APIの二つの経路から, 同等の意味を持つイベントをそれぞれ送信する場合, 同一のdeduplication_keyを設定して重複排除を行う必要があります. LINE Tagでdeduplication_keyを設定するためには, 以下のように追加の記述が必要となります.

_lt('init', {
  customerType: 'lap',
  tagId: '{{ TAG_ID }}',
  deduplicationKey: 'CV_abcdefg'
})

ユーザーマッチについて

Conversion APIを経由してイベントを送信すると, イベントに対してLINE広告が寄与したかどうかを判定するコンバージョン計測処理が行われます. この処理を行うためには, イベントを発生させたエンドユーザーと弊社ユーザーとのマッチングを行う必要があります.

Conversion API経由でのコンバージョン計測処理では, userオブジェクトを用いて弊社ユーザーとのマッチングを行います. そのため, userオブジェクトには, 弊社がユーザーマッチに利用するフィールドを1つ以上含める必要があります.ユーザーマッチできなかったイベントはコンバージョン計測処理の対象となりません. userオブジェクト内の各フィールドの詳細については, 別途LINE Conversion API v1 - Send Conversion Eventのリクエストボディ定義をご確認ください.

弊社内部でのマッピング

userオブジェクトのフィールドのうち, browser_idもしくはexternal_idのいずれか1つを含めることが推奨されます.

browser_idもしくはexternal_idを含めることで, browser_id, external_id以外のユーザー情報を利用してマッチしたユーザー情報の紐付けが内部で作成されます. この資料では, ユーザー情報の紐付けのことを「マッピング」と呼び, browser_id, external_idのことを「マッピングキー」と呼びます. 作成されたマッピングは, 以降送信されたイベントによるコンバージョン判定にも利用されます. また, LINE Tag経由で送信されたイベントに対してもConversion API経由で作成されたマッピングは利用されます. なお, LINE Tag経由で作成されたマッピングもConversion APIで利用されます. マッピングには, 有効期限が設定されており, 一定の期間が経つと削除されるため, 定期的に最新のユーザー情報を送信することによってマッピングを更新することが推奨されます.

ユーザーマッチに利用可能なフィールド

Conversion APIを利用したコンバージョン判定では, イベントを発生させたユーザーと弊社のユーザーとのマッチングが行われます.そのため, ユーザーマッチに利用可能なフィールドを1つ以上含める必要があります. 通常は可能な限り多くのフィールドを含めて送信することが推奨されます. ユーザーマッチに利用可能なフィールドは以下の通りです.

  • user.line_uid (推奨)
  • user.click_id (推奨)
  • user.phone (推奨)
  • user.email
  • user.ifa

以下のフィールドは, 既に弊社内部でのマッピングが作成されている場合に限り, ユーザーマッチに利用可能です.

  • user.browser_id
  • user.external_id

また, 弊社では以下の2つの条件を満たしている場合に限り, イベントを受理します.

  • 弊社内部でのユーザーマッチに成功している
  • お客様から受領した個人関連情報を弊社が個人データとして取得することについて、対象ユーザーが弊社アプリ内で同意している

ユーザーマッチに失敗した場合や, ユーザーの同意が確認できない場合には, イベントは処理されずに破棄されます. イベントが破棄された場合には, 弊社Business Managerの画面上でもConversion APIのステータス状況は更新されませんのでご注意ください.

弊社内部のマッピングが利用されるスコープについて

  • browser_idはファーストパーティクッキーデータであり, お客様の管理するWebサイトのドメインに対して発行されます
  • external_idにはお客様が任意の値を設定できます. ただし, external_idによるマッピングは, 同一のLINE Tag IDで送信されるデータ間でのみ利用可能です. また, 弊社内部ではハッシュ化した値で保持され, ユーザーマッチの際にもハッシュ化した状態で突合されます.

サーバーサイドタグテンプレート 設定ガイドライン

はじめに

サーバーサイドタグテンプレートを利用することで, Google Tag ManagerとLINE Conversion APIの統合を実現し, Server-side taggingを行うことができます.

統合を行うことで, LINE Tagによる広告効果およびユーザー行動の計測に加え, Google Cloud Platform上に構築されたサーバーサイドコンテナを経由した計測を行うことが可能になります. なお, クライアントとしてGA4クライアントのみをサポートしています.

Server-side taggingの概要や説明については, GoogleのServer-side Tagging をご確認ください.

このガイドでは, 以下の説明を行います.

  • サーバーサイドタグテンプレートを利用したサーバータグのインストール方法
  • 実例を踏まえたサーバータグの設定方法
  • サーバーサイドタグテンプレートの追加パラメータについて
  • Server-side taggingにおけるLINE Conversion APIとLINE Tagとの相互運用について
  • 注意事項

このガイドでは, LINE Tag, LINE Conversion API, Google Tag Manager, およびServer-side taggingに関する基本的な知識を必要とします. これらに関する情報は各プロダクトの説明をお客様ご自身でご確認ください.

またこのガイドに記載されている内容は, 最新のGoogle Tag ManagerおよびServer-side taggingに関する仕様と異なる可能性があります. 各プロダクトの最新のドキュメントを確認し, 変更や更新がないかを確認してください.

コミュニティテンプレートギャラリーからインポートする

Googleのコミュニティテンプレートギャラリーからサーバーサイドタグテンプレートをインポートすることで, 後述する手動でテンプレートファイルをダウンロードしてインポートする作業は不要です.

詳しい内容については, Googleの最新のドキュメントをご確認ください.

サーバーサイドタグテンプレートのインポート方法

ここではコミュニティテンプレートギャラリーからではなく直接テンプレートファイルをインポートする方法について説明します.

サーバーサイドタグテンプレートの実体は「.tpl」拡張子を持つファイルです.

サーバーサイドタグテンプレートは, Google Tag Managerの管理画面上からインポートして利用します.

このガイドでは, サーバーサイドコンテナを構築済みであることを前提として, サーバーサイドタグテンプレートのインポート方法を説明します.

構築が完了していない方は, GoogleのServer-side tagging のドキュメントに従ってサーバーサイドコンテナの構築を行なってください.

タグテンプレートの取得

事前に「template.tpl 」を取得してください.

タグテンプレートの新規追加

Google Tag Managerの管理画面に移動し, 既に構築済みのサーバーサイドコンテナのワークスペースを開きます.

左側にある「テンプレート」タブを選択し, タグテンプレートのパネルにある「新規」ボタンをクリックしてテンプレートエディタを開きます.

Tag Manager - New Tag Template

タグテンプレートのインポート

テンプレートエディタが開いたら, 右上のメニューを選択し, 「インポート」をクリックします.

ファイルを選択するダイアログが表示されるので, 事前に取得した「template.tpl」を選択します.

Tag Manager - Import Tag Template

タグテンプレートの読み込みが完了すると, テンプレートのプレビューや, 各種項目の表示が切り替わっていることが確認できます. 右上の保存ボタンをクリックしてテンプレートを保存してください.

Tag Manager - Save Tag Template

タグテンプレートのパネルに, LINE Conversion APIが追加されていればテンプレートのインポートは完了です.

これ以降, サーバータグの設定にこのテンプレートを利用することが可能になります.

Tag Manager - List Tag Templates

実例を踏まえたサーバータグの設定方法

テンプレートを使って実際にサーバータグをコンテナにインストールし, Server-side taggingを実施する例を紹介します.

このステップを完了すると, 以下のようにTag Manager web containerを介してGA4 Clientにイベントを送信し, サーバータグによってLINE Conversion APIにコンバージョンイベントを送ることが可能になります.

Conversion API GTM Overview

タグを設置するウェブページの階層ですが, 今回は単純化のために以下の構成で考えます.

「conversion.html」にアクセスした場合にのみコンバージョンが発生したとみなし, 計測します.

.
├── conversion.html
└── index.html

実際のURLですが, 例えば, https://{ホスト名}/conversion.htmlのようにしてアクセスすることを想定します.

ウェブコンテナの設定

サーバーサイドコンテナにGA4でイベントを送信する手段ですが, 今回はGoogle Tag Manager経由で送信することにします.

このため, 事前にGTMウェブコンテナの設定が必要です. 既にLINE Tagの計測設定をGTMウェブコンテナで管理している場合には, そのまま利用することができます. Google Tag Manager用のタグをまだ設置していない場合は, クイックスタートガイド を参考にして設置してください.

ウェブコンテナへのタグ追加

GA4設定タグは, 2023年9月初旬にGoogleタグに変更されました. 新たにサーバーコンテナにイベントを送信するためには, Googleタグを設定する必要があります.

Google Tag Managerでウェブコンテナのワークスペースを開き, 「タグ」の一覧を表示し「新規」ボタンから新規作成を行います. 「Googleタグ」を選択し, 「設定」の「構成パラメータ」に「server_container_url」を追加してください. その構成パラメータの値に, 事前に構築したサーバーコンテナのURLを入力します. 以上の設定により, Google Tag Managerによって配信されるタグによってサーバーコンテナにイベントを送信が可能となります.

サーバータグが要求する追加のフィールドを受け渡すためには, 「設定フィールド」の項目を設定する必要があります. Google Tag Managerで利用している既存の変数や, 追加したデータレイヤー変数をサーバータグに受け渡す場合にも, この設定が必要です. LINE Conversion APIサーバータグが期待する追加のフィールドの詳細については「サーバーサイドタグテンプレートの追加パラメータについて」を参照してください.

Web Container - GA4 Configuration

なお, 今回のサンプルでは, データレイヤー変数として作成した変数と, 追加で受け渡すパラメータとのマッピングを「設定フィールド」のフィールドと値の組み合わせとして登録しています.

加えて, ウェブコンテナの組み込み変数である「Page Hostname」「Page Path」もサーバータグの発火条件であるトリガーで利用できるように, サーバーコンテナに受け渡しを行なっています. サーバーコンテナ側では, 組み込み変数としてこれらの値は定義されておらず, 代わりに「Request Path」「Query String」などの, 「サーバーコンテナへのリクエスト情報」が定義されており, 大元のウェブページに関するURL情報は取得することができないようです. ( 21 Jun 2022 時点)

Web Container - User-Defined Variables

サーバーサイドコンテナの変数設定

事前準備として, サーバーサイドコンテナで利用する変数の定義を行います.

先ほどのウェブコンテナの設定で, 明示的に設定フィールドとして設定した「Page Hostname」「Page Path」をユーザー定義変数として新たに定義します.

サーバーサイドコンテナのワークスペースを開き, 左側のタブから「変数」を選択, 「新規」をクリックして変数を定義します.

変数タイプを「イベントデータ」とし, キーパスをウェブコンテナ側で設定した値にします.

今回の例では, Page Hostnameを「page_hostname」, Page Pathを「page_pathvar」に設定したので, その値をそれぞれキーパスとして指定する必要があります.

Server Side Container - Add User-Defined Variable

ユーザー定義変数を設定すると以下のようになります.

Server Side Container - List User-Defined Variables

これで, サーバーサイドコンテナ側でも, クライアント側でタグが発火した時のウェブサイトのホスト名とパスを取得できるようになりました.

サーバータグの設定

次にサーバータグの設定を行います. サーバーサイドタグテンプレートは, 先ほどインポートした「LINE Conversion API」を使います.

サーバーサイドコンテナのワークスペースの左側のタブから「タグ」を選択し, タグのパネルから「新規」のボタンをクリックします.

Server Side Container - New Tag

タグ追加のメニューが表示されるため, 「タグの設定」をクリックします.

タグタイプを選択するメニューが表示されるため, カスタムの項目に表示されている「LINE Conversion API」を選択します.

Server Side Container - Select Tag Template

選択すると, 以下のようにサーバーサイドタグテンプレートの設定項目の入力ができるようになります.

各項目の説明についてはツールチップの上にマウスをホバーすることで確認可能ですが, このガイドでも説明を行います. 説明に従って, 項目を入力してください.

Server Side Container - Fill In Template Configuration
  1. LINE Conversion APIを利用する際のLINE Tag IDを入力します.
  2. Business Manager上で発行したConversion API用のアクセストークンを入力します.
  3. LINE User IDを用いて計測を行いたい場合, User IDを発行するChannel ProviderのChannel IDを入力します. ChannelやUser IDについて詳しくは, LINE Developersサイトの「チャネル 」および「ユーザーID 」を参照してください.
  4. 計測したいイベント種別を指定します.
    1. PageViewはベースコードに相当します.
    2. Conversion/Custom Conversionはコンバージョンコードに相当します.
      1. 送信するイベント名が「Conversion」の場合はデフォルトコンバージョンの計測になります.
      2. それ以外のイベント名を送信する場合にはカスタムイベントとして送信されます.
  5. 固定のイベント名を指定します. 固定のイベント名を指定しない場合, GA4でのイベント名から自動的にイベント名が設定されて送信されます. 例えば, GA4でページビューが発生する場合, 「page_view」としてイベント名が設定されます. このイベントに関する説明は, Google Analytics - イベントリファレンス を参照してください. イベント名を明確にコントロールしたい場合には, 常に同じイベントを送信するタグを設定するか, 代わりに適切な変数を設定する必要があります.
  6. Cookieによる計測を有効化します. この設定を有効化することで, First-party Cookieの読み取りだけではなく, サーバーコンテナでFirst-party Cookieを発行することが可能になります. 事前にCustom domain configuration を設定して, サーバコンテナとウェブページを同一のドメイン配下に設定し, First-partyとみなせるように準備しておく必要があります.

タグのトリガーの設定

次に, 設定したサーバータグを発火させるための条件を設定します.

「conversion.html」にアクセスしたときにコンバージョンを計測したい, という前提がありました.

ウェブコンテナのタグが発火したウェブサイトのURL情報を取得し, 条件にマッチする場合にタグが発火するようにトリガーとして設定します.

「トリガー」をクリックして, トリガーの選択画面を表示し, 右上の「新しいトリガー」からトリガーを作成します.

Show Server Side Tag Details

トリガーの設定で, ページビューを選択し, その中でも一部のページビュー, 「Page Hostname」の先頭が期待するホスト名に一致し, 「Page Path」が「/conversion.html」に等しい場合に限り, サーバータグを発火させるように設定します.

Set Triggering to Server Side Tag

これで, サーバタグの設定が完了しました. 「公開」をクリックし, 変更を公開します.

List Configured Server Tags

サーバーサイドコンテナのデバッグ

サーバーサイドコンテナに実際にイベントが送られているか確認する手段が提供されています.

サーバーサイドコンテナの管理画面の「プレビュー」ボタンをクリックし, デバッグ用のページを立ち上げます.

Push Button To Debug Server Side Container

「conversion.html」にアクセスし, ウェブコンテナから実際にイベントを送信することで以下を確認することができます.

  • サーバータグが発火したか発火していないか
  • 実際にLINE Conversion APIに送信されたHTTPリクエストの詳細
  • LINE Conversion APIからのレスポンス
  • イベントデータの中身
  • エラーが発生した場合のログ
Debug Server Side Container

タグが発火する場合, 「Tags Fired」として表示されます.

発火しない場合には「Tags Not Fired」として表示されます. 発火しない場合は, トリガーの設定や送信先のURLが正しいことを確認してください.

Debug Server Side Container - Tag Fired

サーバーサイドタグテンプレートの追加パラメータについて

GA4でイベントをサーバーサイドタグに送信する時に, 自動的に収集されるデータに加えて, 追加で送信が可能なデータがあります.

以下の表の「追加の設定フィールド名」に値を追加で設定することで「LINE Conversion APIの対応するフィールド」に対して, 追加のデータを送信できます.

追加の設定フィールド名 LINE Conversion APIの対応するフィールド
x-line-deduplication_key event.deduplication_key
x-line-hashed_phone user.phone
x-line-hashed_email user.email
x-line-user_id user.line_uid
x-line-external_id user.external_id
x-line-ifa user.ifa
x-line-event-value custom.value
x-line-event-currency custom.currency

Google Tag ManagerのウェブコンテナからGA4でイベントを送信する場合, 「ウェブコンテナの設定」で説明した方法で, 追加の設定フィールドを受け渡すことが可能です.

また, 加えてCommon event data として利用可能な user_data.* のデータについては, 利用のための設定がされている場合に, 以下の対応するフィールドとして値が送信されます. この時, ハッシュされていない値は自動的にハッシュされて送信されます. 設定の詳細についてはGoogleのドキュメントを参照してください.

Common event data LINE Conversion APIの対応するフィールド
user_data.phone_number user.phone
user_data.email_address user.email

イベント重複排除のためのdeduplicationKeyについて

deduplication_keyはイベントの重複排除に利用される必須のフィールドです.

追加の設定フィールドであるx-line-deduplication_keyに何も指定されていない場合, 代わりに都度ランダムなUUIDが生成されて送信されます.

あるイベントを送信するのがServer-side taggingに限定される場合であれば, そのイベントは1回しか送られないため重複排除を行う必要は必ずしもありません.

しかし, イベントが複数経路から送信される場合には, 同じイベントを表すイベントが複数回送信されることになります.

例えば, LINE TagとServer-side taggingを相互運用する場合が当てはまります.

Server-side taggingにおけるLINE Conversion APIとLINE Tagとの相互運用について

Google Tag Managerを用いると, LINE Conversion APIとLINE Tagを相互運用することが可能です.

例えば, このガイドで設定を行ったLINE Conversion APIのタグ設定と, HTMLタグとして追加してあるLINE Tagのタグ設定を併用させると, 同じイベントに対して両方のタグを発火させることが可能です. しかし, この場合にはイベントの重複排除の対応が必須になります. 対応を行わない場合, あるコンバージョンが発生したときに, Conversion APIとLINE Tagそれぞれでコンバージョン判定が行われてしまうことになります. この重複排除については, deduplication_keyを適切に設定する必要があります. deduplication_key自体の詳細な説明はLINE Conversion APIのドキュメントを確認してください.

ここでは, どのようにしてGoogle Tag Managerで設定されたLINE TagとLINE Conversion API Server Tagとで, 同じdeduplication_keyを設定する方法について一例を確認します.

データレイヤー変数にdeduplication_keyを設定する

1つの方法として, データレイヤー変数としてdeduplication_keyを設定する方法があります.

deduplication_keyは, その値のユニーク性が保証されるようにランダムな値を生成し, LINE Tag, LINE Conversion APIの両方で同じ値を受け取れるようにする必要があります.

以下のようにJavaScript関数によってdeduplication_keyを生成し, その結果をデータレイヤー変数に設定します.


<script>
    window.dataLayer = window.dataLayer || [];

    function getDeduplicationKey() {
        return Date.now() + '_' + Math.floor((Math.random() * 10 ** 9));
    }

    dataLayer.push({
        'x-line-deduplication_key': getDeduplicationKey()
    });
</script>

このデータレイヤー変数を, ウェブコンテナではLINE Tagの'deduplicationKey'として設定し, サーバーサイドコンテナでは'x-line-deduplication_key'として受け渡します. このように, 別々の経路でも同じdeduplication_keyを受け渡すことで重複排除が可能となります.

注意事項

  • 弊社で提供するサーバーサイドタグテンプレートの利用の際には, LINE Conversion APIの利用時のプライバシーポリシー及び利用規約が同様に適用されます.
  • 現時点で弊社が提供するサーバーサイドタグテンプレートについては, 全ての動作を正確に保証するものではありません.
  • Google Tag Manager及びGoogle Cloud Platform, Google Analyticsなど, 弊社で提供しない全てのサービスに関する問い合わせは, サービスの提供元に行なってください.
  • 弊社で提供するサーバーサイドタグテンプレートを, 独自で変更したことにより発生した不利益については, いかなる場合であっても補償することはできません.

規約

お客様がConversion APIを利用する場合には, 弊社の Conversion API利用規約 が適用されます. 詳しくは当該規約をご参照ください.

LINE Conversion API v1

Send Conversion Event

Conversion APIを利用すると, LINE Tagで通常送信される情報に加え, コンバージョンイベントに関する追加の情報を送信することができます.

送信されたイベントはLINEでのコンバージョン計測, オーディエンス蓄積, レポーティング, 配信最適化に利用されます.

path Parameters
line_tag_id
required
string

Conversion APIでのコンバージョン計測に利用したいLINE Tag IDを指定します.

header Parameters
X-Line-TagAccessToken
required
string

Business Managerで発行された, Conversion API用のアクセストークンを指定します. Conversion API用のアクセストークンは, line_tag_idパラメーターで指定するLINE Tag IDに紐付くアクセストークンである必要があります.

X-Line-ChannelID
string

チャネルIDを指定します. user.line_uidで指定するLINE User IDを発行したチャネルのチャネルIDを使用してください. LINE User IDを使ったユーザーマッチングを行うためには, このフィールドは必須です.

Request Body schema: application/json
Array
object (WebObj)

source_typewebの場合に, 発生したイベントを表す一連の情報を含むオブジェクトです

required
object (EventObj)

発生したイベントを表す一連の情報を含むオブジェクトです

required
object (UserObj)

イベントを発生させたユーザーを表す一連の情報を含むオブジェクトです.

object (CustomObj)

標準イベントの追加パラメータを含むオブジェクトです. 最適化及びレポーティングで使用される可能性があります.

Responses

Request samples

Content type
application/json
[
  • {
    }
]