Account collegati
Collega gli account Google, Facebook e Apple Business Connect, associa le loro schede alle sedi e scollegali con l'SDK listingsapi-js.
Un account collegato è un'autorizzazione OAuth concessa da un titolare di Google Business Profile, Facebook Pages o Apple Business Connect. Una volta concessa l'autorizzazione, la piattaforma può leggere le schede di proprietà di quell'account e collegare ciascuna a una sede. Tutti i metodi per gli account collegati sono disponibili nell'istanza del client ListingsAPI.
La sequenza abituale è: creare un link di collegamento, attendere l'autorizzazione del titolare, elencare gli account per ottenere un connectedAccountId, avviare l'abbinamento, esaminare i suggerimenti, quindi confermarli oppure collegare una scheda manualmente. Ogni metodo restituisce il payload contenuto nella propria chiave di risposta, indicata nella rispettiva sezione di seguito.
connectGoogleAccount
Crea un link OAuth per Google Business Profile valido per l'intero account. Indirizza il titolare all'url restituito; alla chiusura della schermata di consenso, il titolare torna al tuo successUrl o errorUrl.
const link = await client.connectGoogleAccount('https://app.example.com/onboarding/google/done','https://app.example.com/onboarding/google/failed',); console.log(link.url);Parametri
Restituisce il payload bulkConnectLinkForGoogle: url, success e errors. Controlla url e non solo success, perché un reindirizzamento non utilizzabile può produrre una risposta di successo con url impostato a null. Il link ha una validità breve, quindi creane uno nuovo per ogni tentativo.
connectFacebookAccount
L'equivalente di connectGoogleAccount per Facebook Pages, con gli stessi due argomenti di reindirizzamento.
const link = await client.connectFacebookAccount('https://app.example.com/onboarding/facebook/done','https://app.example.com/onboarding/facebook/failed',); console.log(link.url);Parametri
Restituisce il payload bulkConnectLinkForFacebook: url, success e errors.
getOauthConnectUrl
Crea un link OAuth limitato a una sola sede anziché all'intero account. Usalo quando sai già quale sede il titolare sta collegando e vuoi che torni alla schermata di quella sede nel tuo prodotto.
const link = await client.getOauthConnectUrl(1800289,'GOOGLE','https://app.example.com/locations/1800289/connected','https://app.example.com/locations/1800289/connect-failed',); console.log(link.url);Parametri
Restituisce il payload createConnectUrl: url, success e errors. Entrambi gli URL di reindirizzamento sono obbligatori e devono essere assoluti. Il link è monouso ed è associato alla sede che hai indicato.
fetchConnectedAccounts
Elenca gli account Google e Facebook autorizzati nel tuo account, con lo stato dei collegamenti e il numero di sedi collegate. Qui ottieni il connectedAccountId richiesto da tutti i metodi successivi.
const page1 = await client.fetchConnectedAccounts({publisher: 'GoogleAccount',status: 'Connected',page: 1,perPage: 20,}); for (const record of page1.records ?? []) {console.log(record.email, record.connectedAccountId, record.status);}Opzioni
Restituisce il payload connectedAccountsInfo: un array records e pageInfo con hasNextPage, hasPreviousPage, totalPages e totalRecords. Ogni record contiene connectedAccountId, email, connectedAccountType, connectedLocationsCount, connectivityIssue, status e requestMatchesStatus.
Il filtro e il campo non usano gli stessi valori. L'opzione status accetta 'Connected', 'NotConnected' o 'ConnectionIssue', mentre il campo status di un record può avere il valore CONNECTED, MATCH_IN_PROGRESS o CONNECTIVITY_ISSUE. Se passi il valore di un record come filtro, la richiesta viene rifiutata.
fetchConnectedAccountDetails
Leggi un singolo account tramite il suo ID. Questo metodo richiede meno risorse rispetto alla lettura di tutte le pagine dell'elenco quando hai già l'ID ed è quello da interrogare periodicamente mentre l'abbinamento è in corso.
const details = await client.fetchConnectedAccountDetails('4f712c17-4f95-42dd-90f4-97171a2e67b5',); console.log(details.details.requestMatchesStatus); // MATCH_IN_PROGRESS, then MATCH_COMPLETEDParametri
Restituisce il payload connectedAccountDetails, che contiene il record nella chiave details con gli stessi campi restituiti dall'elenco. Monitora requestMatchesStatus per sapere quando i suggerimenti sono pronti e leggi status e connectivityIssue per decidere se richiedere una nuova autorizzazione.
fetchConnectedAccountFolders
Elenca i gruppi di account Google (cartelle) a cui l'account collegato può accedere. Chiamalo prima di createGmbListing quando il titolare vuole inserire la nuova scheda in un gruppo specifico.
const folders = await client.fetchConnectedAccountFolders('4f712c17-4f95-42dd-90f4-97171a2e67b5',); for (const folder of folders) {console.log(folder.folderId, folder.folderName, folder.locationCount);} // Narrow by nameconst matching = await client.fetchConnectedAccountFolders('4f712c17-4f95-42dd-90f4-97171a2e67b5',{ folderName: 'West Region' },);Opzioni
Restituisce l'array getFoldersUnderGoogleAccount, con un array vuoto come valore predefinito. Ogni cartella contiene folderId (una stringa accounts/<id> da passare senza modificarla), folderName e locationCount, che può essere null quando Google non indica alcun conteggio. Il percorso è valido solo per gli account di tipo Google.
fetchConnectedAccountListings
Elenca le schede sulle piattaforme di pubblicazione a cui l'account collegato può accedere. Il campo id di ogni record è esattamente il connectedAccountListingId accettato da connectListing, quindi puoi usarlo per creare un selettore di schede.
const listings = await client.fetchConnectedAccountListings('4f712c17-4f95-42dd-90f4-97171a2e67b5',{ locationInfo: 'William St', page: 1, perPage: 50 },); for (const record of listings.records ?? []) {console.log(record.id, record.locationName, record.address);}Opzioni
Restituisce il payload connectedAccountListings: records e pageInfo. Ogni record contiene id, locationName, address, phone, liveLink e accountTypeName. Anche se la richiesta sottostante ha la struttura di una richiesta di scrittura, si tratta di una lettura: l'SDK inserisce automaticamente l'ID dell'account e i parametri di paginazione nel corpo della richiesta, come richiesto dall'endpoint.
triggerConnectedAccountMatches
Accoda il processo che recupera tutti i profili a cui gli account indicati possono accedere e li abbina alle tue sedi. Chiamalo subito dopo che un titolare ha completato la schermata di consenso e di nuovo dopo aver creato sedi in blocco.
const result = await client.triggerConnectedAccountMatches(['4f712c17-4f95-42dd-90f4-97171a2e67b5',]); console.log(result.success, result.failedIds);Parametri
Restituisce il payload connectedAccountsTriggerMatches: success e failedIds. Un valore true per success indica che il processo è stato accodato, non che l'abbinamento è terminato. Interroga periodicamente fetchConnectedAccountDetails finché requestMatchesStatus non assume il valore MATCH_COMPLETED, quindi leggi i suggerimenti.
fetchConnectionSuggestions
Leggi gli abbinamenti prodotti, così un operatore può confrontare ogni sede con la scheda sulla piattaforma di pubblicazione prima che venga effettuato qualsiasi collegamento.
const suggestions = await client.fetchConnectionSuggestions('4f712c17-4f95-42dd-90f4-97171a2e67b5',{ page: 1, perPage: 50 },); for (const record of suggestions.records ?? []) {console.log(record.accountType, record.matchedDataDatabaseId, record.locationInfo.name);}Opzioni
Restituisce il payload connectionSuggestionsForAccount: records e pageInfo. Un record di suggerimento non ha un campo id. Il suo identificatore è matchedDataDatabaseId e accountType (GMB, FB o APPLE) indica il tipo di record di abbinamento. Conserva entrambi i valori insieme, perché confirmConnectedAccountMatches ha bisogno di tutti e due per costruire l'ID che accetta. Un account per cui non sono ancora presenti abbinamenti restituisce un array records vuoto.
confirmConnectedAccountMatches
Accetta gli abbinamenti esaminati. La conferma collega ogni sede alla relativa scheda sulla piattaforma di pubblicazione, in modo che i successivi aggiornamenti della sede vengano trasmessi alla scheda.
Costruisci ogni ID a partire da un record di suggerimento: unisci il nome del tipo di record di abbinamento e il valore matchedDataDatabaseId del record separandoli con i due punti, quindi codifica il risultato in base64. GMB corrisponde a GmbLocationMatchedData, FB a FbLocationMatchedData e APPLE a AppleLocationMatchedData.
const TYPES: Record<string, string> = {GMB: 'GmbLocationMatchedData',FB: 'FbLocationMatchedData',APPLE: 'AppleLocationMatchedData',}; const matchRecordId = (record: any) =>Buffer.from(TYPES[record.accountType] + ':' + record.matchedDataDatabaseId).toString('base64'); const approved = (suggestions.records ?? []).map(matchRecordId);const result = await client.confirmConnectedAccountMatches(approved); console.log(result.success, result.failedIds);Parametri
Restituisce il payload confirmConnectMatches: success e failedIds. Controlla success a ogni chiamata: un ID che, una volta decodificato, non corrisponde a uno dei tre tipi produce una risposta con la struttura di una risposta di successo, con success impostato a false e senza failedIds. Quando alcuni ID non vengono elaborati correttamente, failedIds contiene gli ID del database decodificati, non i valori codificati che hai inviato, quindi confrontali con matchedDataDatabaseId per individuare le corrispondenze.
Collegare una singola scheda a una singola sede
Tre metodi completano il collegamento tra una singola scheda per cui è stata trovata una corrispondenza e una singola sede e sono documentati insieme agli altri endpoint delle schede, per evitare di duplicare la documentazione:
- connectListing collega a una sede una scheda per cui è stata trovata una corrispondenza.
- disconnectListing la scollega.
- createGmbListing crea un nuovo Google Business Profile per una sede che non ne ha uno, all'interno di una cartella ottenuta da fetchConnectedAccountFolders.
Usa questi metodi dopo che confirmConnectedAccountMatches ha gestito la maggior parte delle schede di un account, quando resta un punto vendita da associare manualmente.
oauthDisconnect
La stessa operazione di disconnessione di una singola sede, disponibile tramite il percorso OAuth per sede. Accetta gli stessi argomenti e restituisce lo stesso payload, quindi scegli il nome che risulta più chiaro nel tuo codice.
await client.oauthDisconnect(1800289, 'GOOGLE');Parametri
Restituisce il payload disconnectConnectedAccountsLocations, con la stessa chiave restituita da disconnectListing.
disconnectGoogleAccount
Scollega un intero account Google: tutte le sedi collegate tramite quell'account smettono di ricevere aggiornamenti. Usalo quando un cliente interrompe il servizio o trasferisce la proprietà.
await client.disconnectGoogleAccount('4f712c17-4f95-42dd-90f4-97171a2e67b5');Parametri
Restituisce il payload gmbBulkDisconnect, che contiene success. L'operazione si applica a tutte le sedi o a nessuna: per scollegare una singola sede mantenendo l'account, usa disconnectListing. Viene restituito success con valore true anche per un ID sconosciuto, quindi consulta fetchConnectedAccounts dopo l'operazione se ti serve una conferma.
disconnectFacebookAccount
L'equivalente per Facebook, con lo stesso argomento e lo stesso comportamento: l'operazione si applica a tutte le sedi o a nessuna.
await client.disconnectFacebookAccount('9d2b5a41-0c7e-4f83-bb16-2ac43e70d915');Parametri
Restituisce il payload fbBulkDisconnect, che contiene success. Vale la stessa avvertenza: anche un ID sconosciuto produce un esito positivo, quindi verifica con fetchConnectedAccounts.
Flusso di configurazione iniziale tipico
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from env // 1. Send the owner through the consent screenconst link = await client.connectGoogleAccount('https://app.example.com/onboarding/google/done','https://app.example.com/onboarding/google/failed',);console.log('open:', link.url); // 2. After they return, pick up the account IDconst accounts = await client.fetchConnectedAccounts({ publisher: 'GoogleAccount' });const accountId = accounts.records[0].connectedAccountId; // 3. Match its listings against your locationsawait client.triggerConnectedAccountMatches([accountId]); // 4. Poll until matching finisheslet details = await client.fetchConnectedAccountDetails(accountId);while (details.details.requestMatchesStatus !== 'MATCH_COMPLETED') {await new Promise((resolve) => setTimeout(resolve, 5000));details = await client.fetchConnectedAccountDetails(accountId);} // 5. Read the suggestions and confirm the approved onesconst suggestions = await client.fetchConnectionSuggestions(accountId, { perPage: 100 });console.log('found ' + (suggestions.records ?? []).length + ' suggested matches');Risorse correlate
- Schede, gli stessi metodi di collegamento e scollegamento nel contesto delle schede
- Sedi, cerca gli ID delle sedi
- Gestione degli errori, errori tipizzati generati da ogni metodo
- Endpoint degli account collegati, la guida passo passo alle operazioni REST alla base di questi metodi
- Collegare Google e importare le sedi, la guida completa alla configurazione iniziale
- Collegare le pagine Facebook, la variante per Facebook
- Creare un Google Business Profile, la guida a
createGmbListing - Riferimento REST: elencare gli account, dettagli dell'account, cartelle, schede dell'account, avviare la ricerca delle corrispondenze, suggerimenti di collegamento, confermare le corrispondenze, collegare una scheda, scollegare una scheda