コンバージョンAPI
日本語に戻す
このドキュメントが更新されました。
日本語への翻訳がまだ完了していません。
英語の最終更新: 2023/08/09

3: 開発者による実装

このページでは、手動での連携について次の内容を説明します。

このセクションは、手動による連携方法と開発者のリソースを活用してこの連携を完了しようとする場合にのみ適用できます。パートナーを活用してこの連携を完了しようとする場合は、各パートナーの連携に関する指示に従ってください。パートナー連携が完了していれば、このガイドの4:　データの検証セクションにスキップできます。

連携のステップを完了するには、ビジネスマネージャの管理者アクセス権限が必要です。開発者として招待されている場合は、届いているメールからアクセス権限を取得できることがあります。または、ビジネスマネージャの管理者に連絡してアクセス権限をリクエストしてください。

ステップ1: ペイロードを構築する

このセクションでは、コンバージョンリードの連携に関するペイロードの仕様について説明するとともに、サーバーからの送信方法に関する推奨事項を紹介します。

  1. まず、CRMピクセルの[設定]タブからCRM連携ガイドを開きます。

  2. コンバージョンAPIの機能について把握するため、コンバージョンAPIの開発者向けガイドをご覧ください。

  3. ペイロードヘルパーを使用してペイロードを構築することをおすすめします。ペイロードヘルパーでは、ペイロードをフォーマットしたりエラーのチェックを行えます。ペイロードのエラーがすべて解決されたら、ペイロードヘルパー内で[コードを取得]ボタンをクリックして、お使いのプログラミング言語のコードテンプレートを生成できます。

  4. 必須パラメーターを以下に示します。各パラメーターの詳細な説明については、コンバージョンリード連携 - ペイロードの仕様のガイドをご確認ください。このペイロード仕様はコンバージョンリード最適化イベントにのみ使用できます。つまり、このイベントはMetaのリード獲得広告のみに関連するもので、有効なリードIDを持ちます。それ以外のイベントタイプ(ウェブサイトリードなど)に、このペイロード仕様を使用しないようにしてください。

    パラメーター
    名前説明

    event_name

    文字列

    CRM内で使用するリードステージを取得するための自由形式フィールド。

    event_nameパラメーターは、CRMのセールスファネルを通過するリードを示します。未加工リードを含め、更新されるたびに確実に全ステージが送信されるようにします。

    event_time

    整数

    CRMによってリードステージ更新イベントが更新された時刻を秒単位で示すUnixタイムスタンプ。
    このタイムスタンプはリード獲得時刻の後に発生する必要があり、そうでない場合はイベントが破棄される可能性があります。

    action_source

    文字列

    値:system_generated


    (コンバージョンAPIを使うことで、自分の知る限りaction_sourceパラメーターが正確であることに同意するものとします。)

    lead_id

    整数

    ダウンロードされたリードの15桁または16桁のleadgen_id。

    lead_event_source

    文字列

    イベントの送信元のCRMの名前。

    event_source

    文字列

    値:crm



    例
    ペイロードは例えば次のようになります。注:有効なlead_idを使用する必要があり、そうでない場合はシステムでイベントが却下されます。 
    {
    "data": [
        {
            "event_name": "initial_lead",
            "event_time": 1629424350,
            "action_source": "system_generated",
            "user_data": {
                "lead_id": 525645896321548
            },
            "custom_data": {
                "event_source": "crm",
                "lead_event_source": "salesforce"
            }
        }
    ]
}

  5. イベントがペイロード仕様に沿っていないかMetaのリード獲得広告に一致しない場合は、連携用に認識されず、モデルのトレーニングに使用されません。
    例えば、ウェブのペイロードはコンバージョンAPIで受け取られイベントマネージャに表示されますが、この連携用には認識されません。有効なlead_idを使用する必要があり、そうでないとシステムでイベントが却下されます。
    連携用に認識されトレーニングに使用されるのは、コンバージョンリードのペイロードのみです。

ステップ2: アクセストークンとAPI呼び出しを作成する

何を送信するかを設定したら、次のステップではデータの送信場所を設定します。

このステップではMetaピクセルのアクセストークンの生成をサポートします。アクセストークンは、サーバーとコンバージョンAPI間の接続を確立するために使用します。

  1. まず、CRMピクセルの[設定]タブからCRM連携ガイドに戻ります。

  2. [エンドポイントの作成]セクションまでスクロールし、[アクセストークンを生成]ボタンをクリックします。アクセストークンを使ってAPI呼び出しが構築されます。
    連携ガイドに戻るか、またはイベントマネージャの[設定]タブから新しいアクセストークンを生成できます。これには、[コンバージョンAPI]セクションに移動してから、[アクセストークンを生成]リンクをクリックします。

  3. このガイドの以降の手順は、MetaのSDKを使用しているかどうかによって変わります。エラーや診断についてより良いメッセージが提供されることから、Meta Business SDKを使用することをおすすめします。Meta Business SDKでAPI呼び出しを作成するには、ピクセルIDとアクセストークンが必要になります。CRM連携ガイドで[アクセストークンをコピー]をクリックすると、アクセストークンを取得できるので、保存します。コンバージョンAPIの開発者向けガイドや、Metaのペイロードヘルパー内のコードを取得機能で、SDK API呼び出しの例を参照できます。

  4. SDKを使用せずにコンバージョンAPIにPOSTリクエストをするための、エンドポイントフォーマットを以下に示します。CRM連携ガイドで[エンドポイントをコピー]をクリックすると、完全なエンドポイントを取得できるので、保存します。 
    https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN
    • API_VERSION: 現在のマーケティングAPIのバージョンです
    • PIXEL_ID: 各ピクセルのピクセルIDはイベントマネージャで取得できます
    • ACCESS_TOKEN: 上記で生成されたアクセストークンです
  5. マーケティングAPIのリリース日と有効期限はAPIバージョンに関するドキュメントで確認できます。マーケティングAPIの有効期限を迎える前に、必ずコードのAPIバージョンまたはMeta Business SDKを更新してください。期限の切れたバージョンをコードで使用するとエラーが発生し、システムによってイベントが破棄される可能性があります。

ステップ3: ペイロードをテストする(任意)

サーバーにコードを実装する前に、ここでピクセルにテストペイロードを送信しましょう。テストペイロードの送信にはイベントマネージャの[テストイベント]タブを使用します。

  1. [テストサーバーイベント]セクションで、グラフAPIエクスプローラリンクをクリックします。この固有のリンクを使用すると、ピクセルの情報の一部が自動入力されます。(希望する場合、グラフAPIエクスプローラに直接アクセスすることもできます。)test_event_codeの値をメモします。この値は時間が経つと変更されることがあります。

  2. グラフAPIエクスプローラツールで次の手順を実行します。
    1. POSTモードになっていることを確認します。
    2. APIのバージョンとピクセルIDが正しいことを確認します。
    3. JSONビューに切り替えます。
    4. ペイロードを入力します。これは手動で作成することも、ペイロードヘルパーを使用して生成することもできます。必ず前のステップのtest_event_codeパラメーターと有効なlead_idを入力してください。
  3. ピクセルのアクセストークンを入力して、[送信]ボタンをクリックします。

  4. ペイロードに構文やAPIのエラーがなければ、fbtrace_idが記載された完了メッセージが表示されます。

  5. 少し経つと、イベントマネージャの[テストイベント]タブにテストイベントが表示されます。

ステップ4: 本番データを送信する

本番データは、サーバーから直接データが送信される点を除いては、ステップ3で生成したペイロードと同じ形式である必要があります。このステップは連携方法によって異なるため、このセクションでは手順の説明ではなくガイドラインをご紹介します。

  1. マッチングのため、個人を特定できる情報ではなくlead_idを送信します。

  2. 更新時には必ず、Metaで獲得してCRMにダウンロードしたすべてのリードを示す未加工リードイベントを含む、すべてのリードステージを送信するようにします。以下はファネルの一例です。イベント名とステージは広告主が定義するため、この例に従う必要はありません。


    キャンペーンで100件のリードを獲得した場合は、最初のリードステージを表す「未加工のリード」イベントが100件アップロードされることが見込まれます。最初のリードステージを送信すると、リードを受信して処理したことをシステムに知らせることになります。リードがセールスファネルを進むにつれ、「マーケティング対象リード」ステージで70件、「販売機会」ステージで30件、「コンバージョン」ステージで15件のイベントがアップロードされることが見込まれます。

    つまり、このシナリオ例ではキャンペーンで獲得したリードは100件ですが、アップロードされるイベントは215件になると見込まれます。

  3. リードステータスの更新ごとに更新内容をCRMのAPIまたはデータベースから取得するための機能を作成します。続いて、カスタムの機能やMetaのビジネス用SDKを使ってペイロードをMetaのコンバージョンAPIに送信します。連携に最適な方法は、お使いのCRMとデータベースの設定によって異なります。

    以下のパラメーターには変数がおすすめです。
    • lead_id
    • event_name
    • event_time
    例えば、以下はパラメーターの値を明示的に示すペイロードです。 
    {
  "event_name": "initial_lead",
  "event_time": 1628294742,
  "user_data": {
    "lead_id": 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
    以下は変数を使用してデータベースの値を渡すペイロードです。 
    {
  "event_name": lead_stage // "initial_lead"
  "event_time": unix_time // 1628294742
  "user_data": {
    "lead_id": fb_lead_id // 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}

  4. データは1日1回以上アップロードします。CRMへの呼び出しはリアルタイムとするのが理想的ですが、リアルタイムでの連携が現実的でない場合は、毎時や日次でのバッチ処理方法を採用してもかまいません。
    バッチ処理方法を選択する場合、バッチ処理時のリードのスナップショットではなく、リードステータスの変更履歴を取得するようにしてください。例えば、リードのステータスがバッチ処理の間に3回更新される場合、このリードについては最後の更新のイベントだけではなく3件のイベントが見込まれます。
    注:各バッチに含めることができるイベントの数は最大1,000件です。バッチにエラーがあるとバッチ全体が破棄されるので、小規模のバッチを採用し、再試行のロジックを追加することを強くおすすめします。

  5. 任意。問題が発生した場合は、CAPI呼び出しのエラーメッセージを記録し、アラートを作成することをおすすめします。このようなエラーの例外処理を設けてもよいでしょう。

  6. 最大で過去7日分のデータを遡って反映させることができます。この時間差はevent_timeとupload_timeの差で算出されます。一部のデータを遡って反映させるとトレーニングプロセスを高速化できることがあります。

    警告: event_timeの値を変更することによって、7日分以上のデータを反映させようとしないでください。このモデルにおける最適化は正確なタイムスタンプに基づいています。値を変更すると、遡って反映させたデータがすべて破棄される可能性があります。

  7. event_timeの値が必ずリード獲得のタイムスタンプの後であるようにします。そうでない場合、イベントが破棄されることがあります。

  8. 連携によりイベントがMetaにアップロードされている場合、1時間以内にイベントマネージャにピクセルのイベントが表示され始めます。イベントが表示されるようにするため、ペイロードには有効なlead_idを使用してください。コンバージョンリードCRM連携のために送信された各イベントをイベントマネージャで開いて、カスタムパラメーターlead_event_sourceおよびevent_sourceが入力されていることを確認します。これらのパラメーターがイベントにない場合、コンバージョンリードイベントとして登録されません。
  9. イベントが有効なコンバージョンリードイベントかどうかがシステムで確認されます。1日経つと、有効なイベントが検出された場合には連携の[CRMイベントを送信]ステップの横に緑のチェックマークが表示されます。