Bağlı hesaplar
listingsapi-js SDK ile Google, Facebook ve Apple Business Connect hesaplarını bağlayın, işletme kayıtlarını konumlarla eşleştirin ve bağlantılarını kesin.
Bağlı hesap, bir Google Business Profile, Facebook Pages veya Apple Business Connect sahibinin verdiği OAuth yetkisidir. Yetki verildikten sonra platform, bu hesabın sahip olduğu işletme kayıtlarını okuyabilir ve her birini bir konuma bağlayabilir. Bağlı hesaplarla ilgili tüm metotlar ListingsAPI istemci örneğinde bulunur.
İşlemler genellikle şu sırayla yapılır: bir bağlantı kurma bağlantısı oluşturun, hesap sahibinin yetki vermesini bekleyin, bir connectedAccountId almak için hesapları listeleyin, eşleştirmeyi başlatın, önerileri inceleyin, ardından bunları onaylayın veya bir işletme kaydını elle bağlayın. Her metot, aşağıdaki ilgili bölümde adı verilen kendi yanıt anahtarının altındaki veriyi döndürür.
connectGoogleAccount
Google Business Profile için hesap genelinde geçerli bir OAuth bağlantısı oluşturun. Hesap sahibini döndürülen url adresine yönlendirin; izin ekranı kapandığında successUrl veya errorUrl adresinize döner.
const link = await client.connectGoogleAccount('https://app.example.com/onboarding/google/done','https://app.example.com/onboarding/google/failed',); console.log(link.url);Parametreler
bulkConnectLinkForGoogle altındaki veriyi döndürür: url, success ve errors. Yalnızca success değerini değil, url değerini de kontrol edin; çünkü kullanılamayan bir yönlendirme, url değeri null olan başarılı bir yanıt olarak dönebilir. Bağlantının geçerlilik süresi kısadır, bu nedenle her deneme için yeni bir bağlantı oluşturun.
connectFacebookAccount
connectGoogleAccount metodunun Facebook Pages karşılığıdır ve aynı 2 yönlendirme argümanını alır.
const link = await client.connectFacebookAccount('https://app.example.com/onboarding/facebook/done','https://app.example.com/onboarding/facebook/failed',); console.log(link.url);Parametreler
bulkConnectLinkForFacebook altındaki veriyi döndürür: url, success ve errors.
getOauthConnectUrl
Hesabın tamamı yerine tek bir konumla sınırlı bir OAuth bağlantısı oluşturun. Hesap sahibinin hangi konumu bağlayacağını zaten biliyorsanız ve kendi ürününüzde o konumun ekranına dönmesini istiyorsanız bunu kullanın.
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);Parametreler
createConnectUrl altındaki veriyi döndürür: url, success ve errors. Her 2 yönlendirme adresi de zorunludur ve mutlak URL olmalıdır. Bağlantı tek kullanımlıktır ve belirttiğiniz konuma bağlıdır.
fetchConnectedAccounts
Hesabınızda yetkilendirilmiş Google ve Facebook hesaplarını, bağlantı sağlığı bilgileri ve bağlı konum sayılarıyla birlikte listeleyin. Sonraki tüm metotların gerektirdiği connectedAccountId değerini buradan alırsınız.
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);}Seçenekler
connectedAccountsInfo altındaki veriyi döndürür: bir records dizisi ve hasNextPage, hasPreviousPage, totalPages ile totalRecords alanlarını içeren pageInfo. Her kayıt connectedAccountId, email, connectedAccountType, connectedLocationsCount, connectivityIssue, status ve requestMatchesStatus alanlarını içerir.
Filtre ile alan aynı değer kümesini kullanmaz. status seçeneği 'Connected', 'NotConnected' veya 'ConnectionIssue' değerini alırken kaydın kendi status alanı CONNECTED, MATCH_IN_PROGRESS veya CONNECTIVITY_ISSUE değerini taşır. Kaydın değerini filtre olarak geri gönderirseniz istek reddedilir.
fetchConnectedAccountDetails
Tek bir hesabı ID değerine göre okuyun. ID değeri zaten elinizdeyse tüm listeyi sayfa sayfa okumaktan daha az maliyetlidir ve eşleştirme sürerken düzenli aralıklarla sorgulamak için bu metot kullanılır.
const details = await client.fetchConnectedAccountDetails('4f712c17-4f95-42dd-90f4-97171a2e67b5',); console.log(details.details.requestMatchesStatus); // MATCH_IN_PROGRESS, then MATCH_COMPLETEDParametreler
connectedAccountDetails altındaki veriyi döndürür; bu veri, kaydı listenin döndürdüğü alanlarla birlikte details altında içerir. Önerilerin ne zaman hazır olduğunu öğrenmek için requestMatchesStatus değerini izleyin ve yeniden yetkilendirme isteyip istemeyeceğinize karar vermek için status ile connectivityIssue değerlerini okuyun.
fetchConnectedAccountFolders
Bağlı hesabın erişebildiği Google hesap gruplarını (klasörlerini) listeleyin. Hesap sahibi yeni işletme kaydının belirli bir grupta olmasını istiyorsa bu metodu createGmbListing metodundan önce çağırın.
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' },);Seçenekler
getFoldersUnderGoogleAccount dizisini döndürür; varsayılan değer boş bir dizidir. Her klasör folderId (değiştirmeden ilettiğiniz bir accounts/<id> dizesi), folderName ve Google bir sayı bildirmediğinde null olabilen locationCount alanlarını içerir. Bu yol yalnızca Google türündeki hesaplar için geçerlidir.
fetchConnectedAccountListings
Bağlı hesabın erişebildiği yayın platformlarındaki işletme kayıtlarını listeleyin. Her kaydın id değeri, connectListing metodunun aldığı connectedAccountListingId değerinin aynısıdır; böylece işletme kaydı seçimi için bir arayüz oluşturabilirsiniz.
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);}Seçenekler
connectedAccountListings altındaki veriyi döndürür: records ve pageInfo. Her kayıt id, locationName, address, phone, liveLink ve accountTypeName alanlarını içerir. Altta kullanılan istek bir yazma isteği biçiminde olsa da bu bir okuma işlemidir: SDK, uç noktanın gerektirdiği şekilde hesap ID değerini ve sayfalama bilgilerini sizin için istek gövdesine yerleştirir.
triggerConnectedAccountMatches
Belirtilen hesapların erişebildiği tüm profilleri getiren ve bunları konumlarınızla eşleştiren işi kuyruğa ekleyin. Bu metodu hesap sahibi izin ekranındaki işlemi tamamladıktan hemen sonra ve toplu konum oluşturma işlemlerinizden sonra tekrar çağırın.
const result = await client.triggerConnectedAccountMatches(['4f712c17-4f95-42dd-90f4-97171a2e67b5',]); console.log(result.success, result.failedIds);Parametreler
connectedAccountsTriggerMatches altındaki veriyi döndürür: success ve failedIds. success değerinin true olması, işin kuyruğa eklendiği anlamına gelir; eşleştirmenin tamamlandığı anlamına gelmez. requestMatchesStatus alanı MATCH_COMPLETED değerini alana kadar fetchConnectedAccountDetails metodunu düzenli aralıklarla sorgulayın, ardından önerileri okuyun.
fetchConnectionSuggestions
Herhangi bir bağlantı kurulmadan önce bir operatörün her konumu yayın platformundaki işletme kaydıyla karşılaştırabilmesi için eşleştirme işleminin ürettiği eşleşmeleri okuyun.
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);}Seçenekler
connectionSuggestionsForAccount altındaki veriyi döndürür: records ve pageInfo. Öneri kaydında id alanı bulunmaz. Tanımlayıcısı matchedDataDatabaseId alanıdır ve accountType alanı (GMB, FB veya APPLE), eşleşme kaydının türünü belirtir. Bu 2 alanı birlikte saklayın; çünkü confirmConnectedAccountMatches, aldığı ID değerini oluşturmak için her ikisine de ihtiyaç duyar. Henüz eşleşmesi olmayan bir hesap, boş bir records dizisi döndürür.
confirmConnectedAccountMatches
İncelenen eşleşmeleri kabul edin. Onaylama işlemi her konumu yayın platformundaki işletme kaydına bağlar; böylece konumda daha sonra yapılan güncellemeler işletme kaydına aktarılır.
Her ID değerini bir öneri kaydından oluşturun: eşleşme kaydının tür adını ve kaydın matchedDataDatabaseId değerini aralarına iki nokta üst üste koyarak birleştirin, ardından sonucu base64 ile kodlayın. GMB, GmbLocationMatchedData ile; FB, FbLocationMatchedData ile; APPLE ise AppleLocationMatchedData ile eşleşir.
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);Parametreler
confirmConnectMatches altındaki veriyi döndürür: success ve failedIds. Her çağrıda success değerini kontrol edin: kodu çözüldüğünde bu 3 türden birine karşılık gelmeyen bir ID için, success değeri false olan ve failedIds içermeyen, başarılı yanıt biçiminde bir yanıt döner. Bazı ID değerleriyle işlem başarısız olduğunda failedIds, gönderdiğiniz kodlanmış değerleri değil, kodu çözülmüş veritabanı ID değerlerini içerir; bu nedenle bunları matchedDataDatabaseId ile eşleştirin.
Bir işletme kaydını bir konuma bağlama
Üç metot, eşleştirilmiş tek bir işletme kaydı ile tek bir konum arasındaki bağlantıyı tamamlar ve iki kez belgelenmek yerine diğer işletme kaydı uç noktalarıyla birlikte belgelenir:
- connectListing, eşleştirilmiş bir işletme kaydını bir konuma bağlar.
- disconnectListing, bu bağlantıyı kaldırır.
- createGmbListing, Google Business Profile bulunmayan bir konum için fetchConnectedAccountFolders üzerinden alınan bir klasörün içinde yeni bir Google Business Profile oluşturur.
confirmConnectedAccountMatches bir hesabın büyük bölümünü işledikten sonra hâlâ elle eşleştirilmesi gereken bir mağaza varsa bu metotları kullanın.
oauthDisconnect
Bu, konum bazındaki OAuth yolu üzerinden erişilen, tek bir konumun bağlantısını kesmeye yönelik aynı işlemdir. Aynı argümanları alır ve aynı veri yüküyle sonuçlanır; bu nedenle kodunuzda daha anlaşılır olan adı seçin.
await client.oauthDisconnect(1800289, 'GOOGLE');Parametreler
disconnectConnectedAccountsLocations veri yüküyle sonuçlanır; disconnectListing de aynı anahtarı döndürür.
disconnectGoogleAccount
Bir Google hesabının tüm bağlantılarını kesin: bu hesap üzerinden bağlanan tüm konumlar artık güncelleme almaz. Müşteri hizmeti kullanmayı bıraktığında veya sahipliği devrettiğinde bunu kullanın.
await client.disconnectGoogleAccount('4f712c17-4f95-42dd-90f4-97171a2e67b5');Parametreler
success içeren gmbBulkDisconnect veri yüküyle sonuçlanır. Bu işlem ya tüm bağlantıları kaldırır ya da hiçbirini kaldırmaz: hesabı koruyarak tek bir konumun bağlantısını kaldırmak için disconnectListing kullanın. Bilinmeyen bir ID için bile success değeri true olarak döndürülür; bu nedenle emin olmanız gerekiyorsa işlemden sonra fetchConnectedAccounts sonucunu okuyun.
disconnectFacebookAccount
Facebook için aynı işlemi yapan bu metot, aynı argümanı alır ve aynı şekilde ya tüm bağlantıları kaldırır ya da hiçbirini kaldırmaz.
await client.disconnectFacebookAccount('9d2b5a41-0c7e-4f83-bb16-2ac43e70d915');Parametreler
success içeren fbBulkDisconnect veri yüküyle sonuçlanır. Aynı uyarı burada da geçerlidir: bilinmeyen bir ID için de başarı bildirilir; bu nedenle fetchConnectedAccounts ile doğrulayın.
Tipik ilk kurulum iş akışı
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');İlgili kaynaklar
- İşletme kayıtları, işletme kayıtları bağlamında aynı bağlama ve bağlantı kesme metotları
- Konumlar, konum ID'lerini bulma
- Hata işleme, her metodun fırlattığı türü tanımlı hatalar
- Bağlı hesap uç noktaları, bu metotların temelindeki REST işlemlerinin adım adım açıklaması
- Google hesabını bağlama ve konumları içe aktarma, ilk kurulum kılavuzunun tamamı
- Facebook sayfalarını bağlama, Facebook için sürüm
- Google Business Profile oluşturma,
createGmbListingkılavuzu - REST referansı: hesapları listeleme, hesap ayrıntıları, klasörler, hesabın işletme kayıtları, eşleştirmeleri tetikleme, bağlantı önerileri, eşleştirmeleri onaylama, işletme kaydını bağlama, işletme kaydının bağlantısını kesme