はじめに
本記事ではMeta社のFacebookリード獲得広告で取得したリードをアプリケーションから取得する流れについて記述します。
リード獲得広告に関する情報は詳細にドキュメントにまとまっているものの、グラフ API利用にあたってのセットアップなども包括してまとめるのが目的です。
（一時期、ドキュメントの一部が消えていた時期もあったため備忘録的な目的も込めます）
対象読者
開発者向けのドキュメントやそういった関連技術に関する記述が中心となるため、開発者に向けて記述しています。
取り扱う題材からマーケターの方なども参照されるかもしれませんが、開発者以外の方に必要な情報は本記事の中には少ないです。
Facebookのリード獲得広告とは？
ざっくりご説明すると、Facebook/Instagram上で表示される広告内に申込みフォームなどを表示して、直接顧客の情報を獲得できる広告です。
フォームの入力内容（質問）はある程度自由に設定できるため、資料請求フォームや来店予約などを広告上で完結することができます。
参考: リード獲得広告: Facebookでリード獲得広告キャンペーンを掲載する | Meta for Business
記述しないこと
以下について説明すると取り留めがなくなる、またはまだ試せていないため記述しません。
- Meta for Developersアカウントについて
- 広告マネージャの設定について
- APIを利用したフォーム作成方法
- Facebookアプリレビューについて
事前準備
- Facebookの開発者アカウントが必要なため、Meta for Developersの登録を行ってください
- Facebookアプリを作成する必要があるため
- Facebookページを用意してください
- 広告はFacebookページと紐づくため
リード獲得広告で取得した情報を得るまでの流れ
- webhookの通知先を作成する
- Facebookアプリを作成、設定する
- Facebookページとアプリを紐付ける（subscribe）
- フォームを作成する
- テストリードを送信する
- webhookの通知を確認する
- リード詳細を取得する
以降、各項目について説明していきます。
Webhookの通知先を作成する
リード獲得広告からフォーム内容が送信された際に、Facebook Appを介して登録されたwebhook通知先にリアルタイム通知が送信されます。
今回はサンプルなのでwebhook.siteを利用します。
ログイン無しでもリクエストを受け取ることができ、さらにGETリクエストに関しては簡単なレスポンスのカスタマイズもできるため今回使いたい機能も揃っています。
https://webhook.site/ にアクセスするとユニークなURLが生成されます。
検証リクエストを処理するためのエンドポイントを作成する
後述する、Facebookアプリ作成時にwebhook通知先を登録すると、その通知先へ有効性を検証するためのリクエストが送信されます。
このリクエストを適切に処理することで登録が完了します。
具体的にはwebhookを受け取った際に以下処理する必要があります。
- GETリクエスト
- クエリパラメータ
hub.challengeの値を text/plain でそのまま出力する
webhook.siteでURLを生成した後、右上の [Edit] から以下のような設定を行います。
入力後、[Save]で保存され、以降このURLへのGETリクエストではhub.challengeの値が常に返されるようになります。
今回はサンプルなので端折ってますが、もう少しセキュアにする場合以下を追加します。
- クエリパラメータ
hub.modeの値がsubscribeであることを確認する - クエリパラメータ
hub.verify_tokenの値が、Facebookアプリ上で登録したトークン（後述）と同一であることを確認する
Facebookアプリを作成、設定する
アプリの作成については要点になりそうな部分だけ抜粋して記載します。
アプリの作成
ユースケースは「その他」を選択します。
タイプは「ビジネス」がおすすめなようです。
アプリの内容については適宜必要な情報を入力してください。
ちなみに検証用に行うのであれば、ビジネスアカウントとの紐づけは不要です。
Webhook製品をアプリに追加する
「Webhooks」の設定をクリックします。
詳細画面へ遷移するので、左上のセレクトボックスから「Page」を選択します。
「Subscribe to this Object」をクリックし、webhook.siteで生成したURLと適当な文字列を「トークンを認証」へ入力します。
保存後、設定したwebhook URLへ検証リクエストが送信されます。
この際、検証できないとエラーとなって登録ができません。
完了後、Subscribeできるフィールドの一覧が表示されるので leadgen フィールドをsubscribeします。
これを行うことでwebhook通知の内容にリードの情報が含まれるようになります。
最後にアプリをライブモードにして、アプリの設定は完了です。
アプリダッシュボード上部の「アプリのモード」を変更します。
関連ドキュメント
Facebookページとアプリを紐付ける（subscribe）
それでは続いて、グラフAPIエクスプローラーを利用して、アプリをFacebookページへ紐づけましょう。
Facebookページとアプリを紐付けることで、以下の流れを作ることが出来ます。
- Facebookページからリード獲得広告を作成する
- ユーザーがリード獲得広告に対して送信を行う
- アプリが(2)を受け取り、登録されたWebhook通知先へリアルタイム通知を行う
以下はグラフAPIエクスプローラーを使ったアプリの紐づけ方です。
- POSTリクエストへ変更し、
{PageId}/subscribed_apps?subscribed_fields=leadgenをリクエスト入力欄へ入力する-
PageIdはFacebookページの設定画面などで確認してください（15桁ほどの数字の羅列です）
-
- 右カラムの「Metaアプリ」で前工程で作成したアプリを選択する
- 「アクセス許可」で以下の3つを選択する（フィルターで入力して探すと楽です）
-
leads_retrieval: リード獲得広告で取得した情報を読取る許可を行う権限です -
pages_show_list: FBページへのアクセスを許可するための権限です -
pages_manage_metadata: FBページのアクティビティに関するwebhook登録を許可するための権限です
-
- 「ユーザーまたはページ」で自身の広告に紐づけたいFacebookページを選択する
- 「Generate Access Token」をクリック
- リクエスト入力欄横の「送信」ボタンをクリック
以下のようなレスポンスが返ってきたら成功です。
{
"success": true
}
以下が成功時のイメージです。
グラフAPIエクスプローラー上でGETリクエストにして再度実行すると、アプリが紐づけられていることが分かります。
正常に紐づいていない場合、レスポンス内のdataが空になります。
関連ドキュメント
フォームを作成する
今回はインスタントフォームを利用して作成します。
インスタントフォームは広告マネージャー上でリード獲得広告のフォームを作成する機能です。
それではサンプルとなる広告を作成しましょう。
キャンペーン作成時に「リード」を選択します。
「フォームを追加」をクリックし、インスタントフォームの「作成」までスクロールします。
次にフォームを「作成」します。
フォームタイプなどはデフォルトのままでも問題ありません。
「イントロ」「定形の質問」「プライバシーポリシー」は必須項目なので、適当なものを入力してください。（公開時にエラーになるので、キャプチャは省きます）
「質問」セクションではデフォルトで「定形の質問」にメールアドレスと氏名がデフォルトで入っているので、これをそのまま利用します。
フォームについてはそのまま公開してしまって問題ありません。
ここまでで、広告側の準備は完了です。
（広告を公開する必要はありません。お金もかかってしまうので。。）
テストリードを送信する
リード獲得広告テストツールを利用してテストリードを送信します。
webhookの通知を確認する
webhook.siteを確認すると、POSTリクエストが送信されていると思います。
以下のような内容が入っていれば、リード作成は正常に完了しています。
{
"entry": [
{
"id": "111111111111111",
"time": 1686743161,
"changes": [
{
"value": {
"created_time": 1686743160,
"leadgen_id": "111111111111111",
"page_id": "111111111111111",
"form_id": "111111111111111"
},
"field": "leadgen"
}
]
}
],
"object": "page"
}
アプリケーション作成時のwebhook受け取りの注意点
webhook.siteでは必要なかったですが、実際に運用するアプリケーションではすべてのリクエストを受け取るのは（その後の処理にもよりますが大抵）よろしくありません。
そのため、その通知がFacebookからの通知かを検証する手段について記載します。
ドキュメント上ではこう記載されています。
すべてのイベントのお知らせペイロードはSHA256で署名されます。この署名は、リクエストのX-Hub-Signature-256ヘッダーにあり、先頭にsha256=が付きます。ペイロードの確認は必須ではありませんが、推奨されています。
ペイロードを確認する手順は次のとおりです。
ペイロードとアプリのApp Secretを使って、SHA256署名を生成します。
自分の署名とX-Hub-Signature-256ヘッダーにある署名(sha256=の後に続くものすべて)を比較します。署名が一致していれば、そのペイロードは本物です。
webhook通知リクエストのヘッダーとbody、アプリのsecretを使うことで、内容を検証することが可能です。
以下はRailsで書く想定のサンプル(抜粋)です。
def verify_request_signature(request:)
signature_key = 'X-Hub-Signature-256'
signature = request.headers[signature_key]
raise "Invalid request: Couldn't find '#{signature_key}' in headers." if signature.blank?
elements = signature.split('=')
signature_hash = elements[1]
expected_hash = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV.fetch('FACEBOOK_APP_SECRET', ''),
request.body.read)
return if signature_hash == expected_hash
raise "Invalid request: Not matched '#{signature_key}' headers."
end
サンプルではヘッダー内のsignatureと、bodyから生成したSHA256署名が一致しない場合、そのリクエストは正常なリクエストではないものとして扱っています。
関連ドキュメント
リード詳細を取得する
グラフAPIエクスプローラーで発行したアクセストークンを利用して、リード詳細を取得できます。
[leadgen_id]はwebhook.siteで確認したleadgen_idで差し替えてください。
curl -X GET "https://graph.facebook.com/v17.0/[leadgen_id]?access_token=[YOUR ACCESS TOKEN]"
すると以下のようなレスポンスが取得できます。
{
"created_time": "2023-06-14T12:34:53+0000",
"id": "999803211379618",
"field_data": [
{ "name": "email", "values": ["test@example.com"] },
{ "name": "full_name", "values": ["テスト 太郎"] }
]
}
field_data内に格納されている情報が、フォーム作成時の質問内容でvaluesが配列になっているのは複数選択肢の質問を設定することもできるためです。
関連ドキュメント
おまけ
ハマったところ
Q: Lead Ads Testing Toolsで送信したテストリード詳細が取得できない
A: ビジネスアカウントの「統合(Integration)」 > 「リードアクセス(Lead Access)」でトークンを生成したユーザーを割り当ててください（アクセス許可に追加してください）。
自身がアプリ開発者でページ管理者でもある場合、テストリードの内容は問題なく取得できるのですが、アプリ開発者で、ページ管理者の人が送信したテストリードは取得できませんでした。
これはリード詳細を取得する際のアクセストークンを発行したのがアプリ開発者自身なためのようでした。
テストリードにアクセスする権限が無かった、ということですね。
ページの所属するビジネスアカウントのリードアクセス権限が無ければ、一般のユーザーのリード情報を読むことはできない、というのも考えると自然なことです。
ただ、この答えにたどり着くために、Advanced Accessを取得するためのアプリレビューを申請してみたり、ユーザーの権限を剥奪したりと色々なことを行ったため、困った方の参考になるといいなと思います。
ちなみに、おそらくビジネスアカウント上でシステムユーザーを作成し、このユーザーのトークンなどを取得するフローを踏んでいればここまでハマらなかった可能性はあります。（試せていないため予想ですが…）
Q: リード獲得広告テストツールでフォームが表示されない
A: 該当のFacebookページの管理者に追加されているか確認してください。
アプリのロールに管理者として追加されていても、Facebookページ側で管理者に追加されていないと、おそらくページと広告の紐づけが確認できないため表示されないのだと思います。
アクセストークンを長期化する
今回利用したアクセストークンは短期的なもので1時間ほどしか有効期間がありません。
しかし、実際にサーバーサイドなどでグラフAPIへアクセスする際には、1時間で切れてしまっては使い物になりません。
そのため期限を長期化（最短2ヶ月）まで伸ばす方法を説明します。
といってもとても簡単です。
以下を実行してください。（適宜置き換えて）
curl -i -X GET "https://graph.facebook.com/v17.0/oauth/access_token?grant_type=fb_exchange_token&client_id=[APP_ID]&client_secret=[APP_SECRET]&fb_exchange_token=[ACCESS_TOKEN]"
すると以下のようなレスポンスが返却されるはずなので、access_tokenの値が長期化されたトークンになります。
{
"access_token": "LONG_LIVE_ACCESS_TOKEN",
"token_type": "bearer",
"expires_in": 5171935
}
デフォルトでは2ヶ月間が期限となっていますが、このアクセストークンを使用するごとに期限が延長されていくため、APIアクセスを行っている限りは使い続けられるということになります。
アクセストークンデバッガーで期限などを確認できます。
関連ドキュメント
おわりに
一度作り切ってしまえばドキュメントの読み方が分かるが、初見だと情報が散在していて追いづらかったため、この記事を残しました。
わりと調べても前後の情報とつなぎ込めなかったり、コミュニティの質問でも解決されていない内容もあったので、もし誰かが困った時にこの記事がお役に立てば幸いです。
参考
Discussion