FacebookコンバージョンAPIに関する仕様定義書
1. 概要
この連携は、サブスクストアで注文が完了したあとに、条件に合う広告経由の注文だけを対象として、サブスクストアからFacebookコンバージョンAPI向けのデータを外部送信する仕組みです。
ここでは、以下を整理します。
- 連携の全体像と通信形式
- リクエスト構造の定義
- サブスクストア独自タグの変換仕様
- トラブルシューティング
2. 連携の全体像と通信形式
2-1. 何をする仕組みか
広告をクリックして来訪した人が購入したときに、その購入情報をFacebookへ送るための仕組みです。
流れは以下です。
- 広告URLに と、媒体ごとのクリックIDが付与される
- フロント側で と をCookieに保存する
- 注文完了時、対象のソケット通信設定がONなら非同期ジョブを起動する
- 注文者情報・注文情報・Cookie情報を元に、送信用JSONを組み立てる
- 設定されたエンドポイントへGETまたはPOSTで送信する
- 結果を送信履歴とログに残す
2-2. 送信される条件
注文時に毎回送られるわけではなく、以下を満たしたときだけ送信されます。
- 注文が成功していること
- ソケット通信設定がONであること
- 対象広告の が一致していること
- が取得できていること
補足
- フロント注文では、Cookieの と を使います
- API経由注文では、 と パラメータを使います
- Facebook向けの項目は、ショップ設定 がONのときだけ値が入ります
2-3. 通信方式
サブスクストアの内部名称は「ソケット通信」ですが、実際の送信は一般的なHTTP通信です。
- 送信方式： または
- ヘッダー：
FacebookコンバージョンAPI用途では、 + を使用する想定です。
2-4. 送信タイミング
基本の送信タイミングは「注文登録完了後」です。
つまり、利用者が購入を完了し、注文データが正しく作成されたあとで送信が走ります。
3. リクエスト構造の定義
3-1. 基本方針
送信内容は、管理画面で設定した「JSONテンプレート」または「キー・値形式」に、サブスクストア独自タグを埋め込んで作成します。
FacebookコンバージョンAPIでは、JSONテンプレート方式の利用を推奨します。
3-2. Facebook向け推奨リクエスト例
以下は、現在の仕組みに合わせた推奨例です
{
"data": [
{
"event_name": "Purchase",
"event_time": "@@ordered_at@@.unixtime",
"action_source": "@@action_source@@",
"event_source_url": "",
"user_data": {
"em": ["@@email@@.sha256"],
"ph": ["@@international_tel@@.sha256"],
"fn": "@@first_name@@.sha256",
"ln": "@@last_name@@.sha256",
"zp": "@@zip_code@@.sha256",
"ct": "@@city@@.sha256",
"st": "@@prefecture_name@@.sha256",
"country": "jp",
"client_ip_address": "@@ip_address@@",
"client_user_agent": "@@user_agent@@",
"fbc": "@@fbc@@",
"fbp": "@@fbp@@"
},
"custom_data": {
"currency": "JPY",
"value": "@@order_total@@",
"order_id": "@@order_id@@",
"content_ids": @@item_code@@,
"content_type": "product"
}
}
]
}
3-3. 項目の意味
主な項目の意味は以下です。
| 項目 | 意味 | サブスクストアでの主な元データ |
| 何の出来事か | 固定値 | |
| いつ起きたか | 注文日時 | |
| どこで起きた購入か | 端末種別から変換 | |
| 購入者を特定しやすくする情報 | 会員情報、住所、Cookie、IP、ブラウザ情報 | |
| 購入内容そのもの | 注文番号、金額、商品コードなど |
3-4. action_source の変換ルール
注文時の利用端末から、Facebook向けの値へ変換します。
| サブスクストアの端末区分 | Facebookへ送る値 |
| その他 |
3-5. item_code の扱い
は、注文商品ごとの配列データを生成するための特別な置換項目です。
例えば以下のような定義を入れると、商品ごとのコード一覧を作れます。
JSON
または、より詳しく持たせたい場合は次のように構成できます。
JSON
[
{
"id": "@@item_sku@@",
"quantity": @@item_quantity@@,
"item_price": @@item_price@@
}
]
4. サブスクストア独自タグの変換仕様
4-1. 基本ルール
サブスクストアでは、 という書き方で値の差し込みを行います。
例です。
- → 購入者メールアドレス
- → 注文番号
- → 購入経路の種別
4-2. Facebook連携でよく使うタグ
| タグ | 内容 |
| メールアドレス | |
| 電話番号 | |
| 国番号付き電話番号から を除去した値 | |
| 名 | |
| 姓 | |
| 郵便番号 | |
| 都道府県名 | |
| 都道府県コード | |
| 市区町村 | |
| 町名番地 | |
| 建物名 | |
| 生年月日 | |
| 購入時IPアドレス | |
| 購入時ブラウザ情報 | |
| 注文日時 | |
| 端末区分から変換した値 | |
| 固定値 | |
| FacebookクリックID | |
| FacebookブラウザID | |
| 注文合計金額 | |
| 注文番号 | |
| 商品ごとの配列データ |
4-3. 自動変換ルール
特定の書き方をすると、送信前に自動変換されます。
| 書き方 | 動き |
| SHA-256でハッシュ化する | |
| UnixTimeに変換する |
やさしく言うと、Facebookに合わせて「個人情報を変換してから送る」「日時の形式を変えて送る」という仕組みです。
4-4. JSON形式での変換ルール
JSON形式では、次の3種類を扱えます。
- 単一値
- 配列
- オブジェクトの中の値
例です。
JSON
{
"event_name": "@@event_name@@",
"user_data": {
"em": ["@@email@@.sha256"],
"ph": ["@@international_tel@@.sha256"],
"client_ip_address": "@@ip_address@@"
}
}
4-5. Facebook連携用フラグの影響
ショップ設定 がOFFの場合、Facebook向けの個人関連項目は になります。
対象になりやすい項目は以下です。
- 氏名
- 郵便番号
- 都道府県
- 市区町村
- 住所
- 建物名
- 生年月日
- IPアドレス
- ユーザーエージェント
つまり、設定がOFFのままだと、送信自体は行われてもFacebookでの突合精度が落ちる可能性があります。
4-6. fbc / fbp の注意点
現在のソケット通信では、Cookieから以下のキー名で値を取得します。
一方で、一般的なブラウザCookie名は と です。
そのため、実運用では次を事前確認してください。
- ブラウザ上で実際に保存されているCookie名
- サブスクストア側へ渡しているCookieデータのキー名
- と に値が入るか
5. トラブルシューティング
5-1. 送信されない
まず確認するポイントです。
確認項目内容注文成功注文が正常完了しているかソケット通信ON対象設定がONかad_code注文時の広告コードが一致しているか
click_idCookieまたはパラメータに入っているかエンドポイントHTTPSで設定されているか
5-2. / が空になる
主な確認ポイントです。
- ブラウザCookie名が / になっていないか
- サブスクストアへ渡すCookieデータに / として入っているか
- ショップ設定 がONか
5-3. 氏名や住所が になる
考えられる原因です。
- FacebookコンバージョンAPI利用フラグがOFF
- 注文者の住所情報が未登録
- ゲスト購入などで対象情報が不足している
5-4. Facebook側でイベントが受理されない
確認ポイントです。
- が になっているか
- が UnixTime になっているか
- ハッシュ化対象が で設定されているか
- 金額や商品情報の形式がFacebook側要件と合っているか
- で送られているか
5-5. HTTPエラーになる
この仕組みでは、HTTPステータスコードが 以外の場合は失敗扱いになります。
主な例です。
- 系：リクエスト形式不正
- / ：認証情報不足、権限不足
- ：送信先URL誤り
- 系：送信先システム側エラー
5-6. どこを見れば原因が分かるか
確認先は次の2つです。
確認先見る内容
送信日時、成功/失敗、HTTPステータス
実際に送った内容、返ってきた内容