Listings APIListings API
サインイン

Facebookページを接続する

Facebookの接続リンクを作成し、オーナーのページを拠点と照合し、候補を確認してリンクを確定するか手動でリンクを選択し、クライアントとの契約が終了したらアカウントの接続を解除します。

Facebookアカウントを接続すると、Facebook上でその拠点の投稿公開とレポート作成が可能になります。ページをリンクすると、投稿でpostSitesのFACEBOOKを対象に指定できるようになり、Facebookの分析エンドポイントがnullの代わりにページの指標を返し、ページがレビューの取得元として追加されてそのレビューもほかのレビューと一緒に届くようになり、拠点のプレミアム掲載情報にあるFacebookの行がREQUIRING_ACTIONではなくなります。

手順はGoogleと同じで、リンクの作成、オーナーによる同意、照合、確定の順に進めます。Facebookで値が異なる箇所は、その都度明記します。

Facebookページには、Facebook上であらかじめ営業時間を設定しておく必要があります。拠点にbusinessHoursがあっても、営業時間が設定されていないページに対するListingsAPIからの更新はFacebookに拒否されます。その場合、Facebookの掲載情報はIN_PROGRESSのままとなり、営業時間がないことを示すsyncIssueが付きます。修正するには、Facebook上でページに営業時間を追加してから、拠点の更新を送信します。

リクエストボディに含めるのは、2つのリダイレクトURLだけです。リンクの対象範囲はキーを所有するアカウントに限定され、有効期間は24時間です。

Connect link
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-facebook \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "successUrl": "https://app.example.com/connect/facebook/success",    "errorUrl": "https://app.example.com/connect/facebook/error"  }}'
JSON
{  "data": {    "bulkConnectLinkForFacebook": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}

上記のurlはプレースホルダーです。実際のレスポンスで返されたurlにオーナーを誘導してください。

オーナーをurlにリダイレクトします。オーナーはFacebookの利用規約に同意し、ページの権限を付与した後、指定したsuccessUrlに移動します。

2. OAuthから戻ったら接続済みアカウントを一覧表示する

publisher=FacebookAccountで絞り込みます。これはオフセット方式のページで、records[]とpageInfo.totalRecordsを含み、pageとperPageでページを切り替えます。

List accounts
curl "https://listingsapi.com/api/v4/connected-accounts?publisher=FacebookAccount&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectedAccountsInfo": {      "pageInfo": { "hasNextPage": false, "totalRecords": 1 },      "records": [        {          "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d",          "connectedAccountType": "FacebookAccount",          "status": "CONNECTED",          "requestMatchesStatus": "MATCH_COMPLETED",          "connectedLocationsCount": 0        }      ]    }  }}

connectedAccountIdを保存しておきます。statusはCONNECTED、MATCH_IN_PROGRESS、またはCONNECTIVITY_ISSUEです。CONNECTED以外の場合、以降の手順を実行するにはオーナーによる再認可が必要です。

3. 照合を開始し、完了を待つ

照合では、アカウントがアクセスできるページを取得し、各ページをいずれかの拠点と対応付けます。照合はバックグラウンドで実行されるため、requestMatchesStatusがMATCH_COMPLETEDになるまでアカウントの詳細をポーリングします。それより前に候補を取得すると、空のrecords配列が返され、「一致する候補なし」のように見えます。

Trigger and poll
curl -X POST https://listingsapi.com/api/v4/connected-accounts/trigger-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountIds": ["d2397854-52c2-41d7-95f1-b90cba16498d"] } }' # then, every 15 seconds until requestMatchesStatus is MATCH_COMPLETEDcurl https://listingsapi.com/api/v4/connected-accounts/d2397854-52c2-41d7-95f1-b90cba16498d/details \-H "Authorization: API $LISTINGSAPI_KEY"

詳細レコードはdata.connectedAccountDetails.detailsで返されます。MATCH_COMPLETEDは照合処理の完了を意味しますが、確定するまでは何もリンクされないため、この時点ではconnectedLocationsCountは0のままです。

4. 候補を確認して確定する

各レコードは、拠点（locationInfo、locationId）とページ（suggestedLocationInfo）を対応付けます。Facebookアカウントでは、accountTypeがGMBではなくFBとなるため、確定時に送信するidが変わります。

Suggestions
curl "https://listingsapi.com/api/v4/connected-accounts/d2397854-52c2-41d7-95f1-b90cba16498d/connection-suggestions?page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

候補にはidがありません。accountTypeから型を選び、<MatchRecordType>:<matchedDataDatabaseId>をbase64でエンコードして作成します。リファレンスに掲載されているのはGoogleの例だけで、デコードするとGmbLocationMatchedData:...になりますが、型は掲載先ごとに異なります。FacebookではFbLocationMatchedDataなので、FBと0d5e306f-0da0-46e3-929f-fd3c67ccd8ccを組み合わせるとRmJMb2NhdGlvbk1hdGNoZWREYXRhOjBkNWUzMDZmLTBkYTAtNDZlMy05MjlmLWZkM2M2N2NjZDhjYw==としてエンコードされます。

accountType照合レコードの型
GMBGmbLocationMatchedData
FBFbLocationMatchedData
APPLEAppleLocationMatchedData
Confirm matches
# base64 of FbLocationMatchedData:0d5e306f-0da0-46e3-929f-fd3c67ccd8cccurl -X POST https://listingsapi.com/api/v4/connected-accounts/confirm-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "matchRecordIds": ["RmJMb2NhdGlvbk1hdGNoZWREYXRhOjBkNWUzMDZmLTBkYTAtNDZlMy05MjlmLWZkM2M2N2NjZDhjYw=="] } }'

レスポンスはdata.confirmConnectMatchesで、successと、確定できなかったデコード済みのデータベースidであるfailedIdsを含みます。誤った型で作成したidを送信すると、success: falseを含みfailedIdsを含まない200が返されるため、必ずsuccessを確認してください。

5. ページを拠点に手動でリンクする

照合処理で確実に対応付けられない場合や、照合の実行後にページが作成された場合は、アカウントから参照できるページを一覧表示し、対象のページを直接リンクします。connectedAccountIdは掲載情報を取得する呼び出しのJSONボディに指定します。クエリパラメーターとして指定すると無視され、最初の接続済みアカウントの掲載情報が返されます。

Pick and link
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connected-account-listings \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d", "locationInfo": "Lincoln" }' curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d",    "connectedAccountListingId": "<id from the listings response>"  }}'

各掲載情報レコードには、id、locationName、address、liveLinkが含まれます。そのidがconnect-listingに渡すconnectedAccountListingIdであり、フィールド名はlistingIdではありません。リンクに失敗すると、Listing record not foundなどのmessageを含むsuccess: falseが返されます。

6. クライアントとの契約終了時にアカウントの接続を解除する

接続解除は一括で行われます。アカウントを通じてリンクされたすべてのページで同期が停止し、Facebookでのインタラクションも届かなくなります。アカウントを維持したまま1つの拠点を切り離すには、代わりにdisconnect-listingを使用します。

Disconnect
curl -X POST https://listingsapi.com/api/v4/connected-accounts/disconnect-facebook \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d" } }'

レスポンスはdata.fbBulkDisconnectで、successを伴います。不明なconnectedAccountIdに対してもtrueとなるため、これは「処理済み」を意味し、「有効な接続が削除された」ことを意味するものではありません。確実に確認する必要がある場合は、接続済みアカウントの一覧を再度取得してください。

7. この後の動作

リンクされた各拠点で、data.platform: "facebook"を含むconnection.location_connectedイベントが発生し、リンクを解除するとconnection.location_disconnectedが発生します。Facebookが許可を無効にするとconnection.reauth_requiredを受信するため、新しいリンクを作成し（手順1）、すべての権限について再度同意するようオーナーに依頼してください。リンクされると、拠点のプレミアム掲載情報にあるFacebookの行がSYNCEDに移行し、postSites: ["FACEBOOK"]が有効な対象となり、Facebookの分析エンドポイントがデータを返し始めます。

次の手順