Ringkasan Integrasi

Iklan Layanan Lokal (LSA) untuk berpartner dengan agregator dalam menampilkan listingan mereka (atau penyedia) di Google.com. Dalam panduan ini, kami menjelaskan cara agregator dapat memberikan data terstruktur LSA tentang penyedia mereka. Secara khusus, kami mendokumentasikan kumpulan endpoint API yang harus diterapkan oleh agregator untuk berintegrasi dengan LSA.

Glosarium

Agregator (atau partner): Ini adalah partner yang mengagregasi penyedia yang mereka berikan layanan dan yang datanya dapat diberikan kepada LSA.

Penyedia (atau listingan) pihak ketiga: Ini adalah bisnis kecil individual (misalnya, Joe’s plumbing) yang mungkin memiliki hubungan bisnis dengan agregator. Agregator memberikan informasi tentang bisnis ini kepada Jasa dan Servis.

Ringkasan

Agregator akan memberikan data tentang penyedia (bisnis) mereka ke Penyedia Jasa Lokal menggunakan feed. Setiap feed terdiri dari data tentang beberapa penyedia. Dalam feed, data tentang satu penyedia diringkas oleh item feed. Setiap feed juga menentukan stempel waktu feed yang menunjukkan keaktualan feed. Setiap feed juga menentukan jenis feed: ini dapat berupa data tentang profil penyedia atau ulasan penyedia seperti yang dijelaskan di bawah.

Jenis feed

Untuk integrasi awal, setiap feed dapat berupa salah satu jenis feed berikut:

  • Feed profil: Feed ini memberikan informasi tentang profil penyedia. Setiap item feed merangkum informasi profil tentang penyedia tertentu. Hal ini mencakup ID bisnis unik, nama bisnis, lokasi penayangan, layanan yang ditawarkan, jam operasional, dll. Item feed juga berisi metadata penayangan untuk bisnis ini (misalnya, jumlah anggaran bulanan, status iklan, dll.).

  • Feed ulasan: Feed ini memberikan informasi tentang ulasan penyedia. Setiap item feed merangkum daftar ulasan konsumen mendetail tentang penyedia tertentu. Setiap ulasan konsumen terdiri dari nama konsumen, rating (1 - 5), teks ulasan, stempel waktu ulasan, dll.

Detail selengkapnya tentang kolom tertentu dan semantiknya di Feed profil dan Feed ulasan.

Penyerapan feed

Data feed diserialisasi sebagai JSON. Untuk mengirimkan data, LSA hanya akan mendukung mekanisme penarikan. Ada rencana pada masa mendatang untuk mendukung mekanisme push.

Mekanisme penarikan

Dalam mekanisme penarikan, agregator mendukung serangkaian endpoint REST (URL) yang telah ditentukan sebelumnya yang mengirim dan menerima objek JSON. Hal ini serupa dengan menghosting satu atau beberapa file di server web. LSA akan secara berkala mengirimkan permintaan HTTP GET ke URL ini untuk mengambil data. Detail tentang URL yang telah ditentukan sebelumnya dapat ditemukan di bagian berikutnya tentang endpoint API.

Mekanisme push

Dalam mekanisme push, LSA akan menyediakan endpoint bagi agregator untuk memanggil dan menyediakan data. Secara semantik, ini sama dengan penarikan, tetapi memberikan fleksibilitas dalam kasus saat agregator ingin mengirim data tertentu ke Layanan Lokal. Semua semantik, aturan, atau batasan yang dijelaskan dalam protokol berlaku untuk push dan pull dengan cara yang sama.

endpoint API

Endpoint berikut harus didukung oleh agregator: satu untuk feed profil dan satu untuk feed ulasan.

Sebaiknya endpoint berisi informasi versi seperti di bawah. Kita mulai dengan v1.

Endpoint Jalur
Feed profil /feeds/{version}/profile
Meninjau feed /feeds/{version}/review

Parameter endpoint

Params Deskripsi
maxresults Ini adalah batas jumlah item feed yang dapat diminta dalam satu halaman.
nextpagetoken Token penomoran halaman untuk mendapatkan halaman hasil berikutnya

Autentikasi Endpoint

Autentikasi menggunakan autentikasi akses dasar HTTP: nama pengguna dan sandi berenkode base64 untuk autentikasi. Berikut contohnya.

  • username “Otorisasi” (untuk tujuan ilustrasi)
  • password J9adfdsafc3RfMjpVU1yif5XMw” (untuk tujuan ilustrasi)

Dropbox SFTP untuk Push

Jalur Dropbox: partnerupload.google.com:19321

PERINGATAN: File yang dimuat ke kotak kirim SFTP ini akan otomatis dihapus setelah 24 jam.

Autentikasi Endpoint

  • Pasangan kunci publik/pribadi (direkomendasikan)

    • Gunakan tutorial di sini untuk membuat pasangan kunci.
    • Mengirim kunci publik ke LSA dan menyimpan kunci pribadi untuk autentikasi
    • LSA akan menggunakan kunci publik untuk membuat nama pengguna dan mengirimkannya kembali ke agregator

  • Autentikasi sandi

    • LSA akan membuat nama pengguna dan sandi, lalu mengirimkannya kembali ke penggabung

Referensi cepat perintah SFTP

  1. Log in. Gunakan perintah ini untuk login. (Jangan sertakan -i jika Anda tidak menggunakan kunci pribadi).

    sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.com

  2. Menyalin file. Salin file ke dalam sistem jarak jauh. Anda dapat menggunakan lls/lcd untuk ls/cd ke sistem lokal Anda guna menemukan file. Kemudian, salin file melalui:

    put <path_to_local_file>

  3. Verifikasi. Gunakan ls untuk melihat daftar folder dan file di direktori SFTP dan verifikasi bahwa file Anda telah disalin ke sistem jarak jauh

Kategori Feed

Seperti yang disebutkan sebelumnya, setiap feed dianalogikan dengan file dan terdiri dari beberapa item feed. Setiap item feed mengenkapsulasi data tentang penyedia tertentu (ID bisnis unik). Setiap feed juga memiliki stempel waktu yang menunjukkan keaktualan feed ini. Kategori Feed menentukan cara LSA menafsirkan feed tertentu. Ada dua kategori feed seperti yang dijelaskan di bawah.

Feed snapshot berisi daftar lengkap penyedia (di bawah agregator) pada stempel waktu tertentu. Setelah memproses feed snapshot ini, semantik berikut berlaku:

  • Untuk setiap penyedia yang ada dalam feed, sistem akan memperbarui data untuk penyedia ini di database LSA (misalnya, membuat penyedia baru jika ditemukan untuk pertama kalinya, atau memperbarui data penyedia jika penyedia diproses dalam feed sebelumnya).

  • Untuk penyedia mana pun di bawah agregator yang saat ini ada dalam database LSA, tetapi tidak ada dalam feed, penyedia tersebut akan dihapus.

Feed pembaruan (atau Inkremental) berisi daftar sebagian penyedia (di bawah agregator) pada stempel waktu tertentu. Setelah memproses feed inkremental, semantik berikut akan berlaku:

  • Untuk penyedia yang ada di feed, sistem akan memperbarui data untuk penyedia ini di database LSA jika penyedia dibuat di feed snapshot sebelumnya. (misalnya, jika penyedia ditemukan untuk pertama kalinya, penyedia tersebut akan menjadi no-op)

  • Untuk penyedia yang saat ini ada di database LSA, tetapi tidak ada di feed, ini adalah operasi no-op (yaitu, tidak akan ada perubahan pada penyedia ini).

Semantik untuk feed profil vs. ulasan sedikit berbeda. Lihat semantik feed individual untuk mengetahui detail pemrosesan.

Feed profil: * Feed Snapshot berbasis pull * Feed Snapshot berbasis push * Feed Pembaruan berbasis push Feed ulasan: * Feed Snapshot berbasis pull * Feed Snapshot berbasis push

Feed profil terpisah diperlukan untuk:

  1. Penyedia yang dianggap memenuhi syarat untuk mendapatkan badge Dijamin oleh Google atau Diseleksi oleh Google.

  2. Penyedia yang tidak memenuhi syarat untuk mendapatkan badge.

Contoh

Feed snapshot

Ingatlah bahwa feed snapshot akan terdiri dari daftar lengkap penyedia. Misalnya, jika agregator ingin 100 penyedia dimasukkan ke dalam LSA, feed snapshot harus berisi status terbaru untuk semua 100 penyedia.

Cara kerjanya

Berikut adalah contoh sederhana yang menunjukkan cara kerja feed profil kategori snapshot.

  • Snapshot 1 memiliki Pro 1, Pro 2
  • Snapshot 2 memiliki Pro 1, Pro 3

Setelah memproses Snapshot 1, database LSA akan memiliki Pro 1 dan Pro 2. Selama pemrosesan Snapshot 2, LSA akan memperbarui Pro 1, membuat Pro 3, dan Menghapus Pro 2. Artinya, setelah pemrosesan Snapshot 2, database LSA akan memiliki Pro 1 dan Pro 3.

Memperbarui feed (Inkremental)

Ingatlah bahwa feed pembaruan berisi daftar sebagian penyedia di bawah agregator. Misalnya, jika agregator hanya ingin memperbarui 5 dari 100 penyedia yang sebelumnya diberikan, feed update hanya perlu berisi status terbaru untuk 5 penyedia ini.

Cara kerjanya

Berikut adalah contoh sederhana yang menunjukkan cara kerja kategori pembaruan “feed profil”.

  • Update 1: Pro 1, Pro 2
  • Pembaruan 2: Pro 1, Pro 3

Setelah memproses Update 1, database LSA akan memiliki Pro 1 dan Pro 2. Selama pemrosesan Update 2, LSA akan memperbarui Pro 1, dan membuat Pro 3. Perhatikan bahwa Pro 2 tidak tersentuh. Artinya, setelah pemrosesan Update 2, database LSA akan memiliki Pro1, Pro2, dan Pro 3.

Implikasi Snapshot dan Tarik

Mekanisme snapshot feeds + pull memiliki batasan berikut:

  • Mungkin ada penundaan beberapa jam bagi partner untuk menambahkan atau menghapus penyedia, memperbarui informasi profil, menjeda iklan, atau mengubah anggaran. Penundaan terkait langsung dengan frekuensi permintaan pull.
  • Untuk pembaruan data mendesak, kami mungkin perlu mendukung penarikan data satu kali/ad-hoc secara manual.

Implikasi dukungan Inkremental dan Push

Membuka mekanisme perbarui feed + kirim menyiratkan peningkatan berikut:

  • Partner dapat mengirimkan feed ringkasan dalam metode push atau pull. Partner yang lebih memilih untuk tidak mengelola endpoint (untuk penarikan) dapat menggunakan push sebagai gantinya untuk mengurangi biaya pengelolaan endpoint. Partner yang sudah mendukung feed snapshot dalam penarikan dapat terus mengirimkan snapshot dalam penarikan.
  • Partner dapat menggunakan inkremental untuk memperbarui hanya sebagian kecil penyedia dengan perubahan profil. Hal ini meningkatkan keaktualan data profil.
  • Terkait cara memilih snapshot vs. inkremental, push vs. pull, lihat bagian ini untuk mengetahui pendekatan integrasi yang direkomendasikan.

Partner diwajibkan untuk memiliki feed snapshot berkala, baik melalui push atau pull. Hal ini memungkinkan LSA menangani keadaan darurat seperti rollback dan pemulihan sistem jika terjadi update yang terlewat.

  • Dengan mekanisme push, partner harus mengirimkan feed profil snapshot setiap 2 jam dan meninjau feed setiap 6 jam untuk menjamin keaktualan data dasar.
  • Dengan mekanisme penarikan, LSA akan menarik feed profil snapshot setiap 2 jam dan meninjau feed setiap 6 jam untuk menjamin keaktualan data dasar.
  • Partner hanya memerlukan salah satu mekanisme (push atau pull), bukan keduanya, untuk mengirimkan feed snapshot.

Secara opsional, partner yang ingin meningkatkan keaktualan data dapat mengirimkan feed pembaruan melalui push. LSA tidak akan menarik feed update.

  • Feed pembaruan digunakan untuk menyebarkan item yang berubah sejak snapshot terakhir tanpa menunggu snapshot berikutnya.
  • LSA merekomendasikan penyedia untuk memiliki interval lebih dari 5 menit di antara dua push.
  • Sebaiknya gabungkan item feed secara wajar dalam feed pembaruan. Untuk memperbarui 5 penyedia, LSA lebih memilih penyedia untuk mengirimkan 1 feed update dengan 5 item feed daripada mengirimkan 5 feed update dengan 1 item feed di setiap feed.
  • LSA hanya mendukung feed inkremental untuk feed profil, bukan untuk feed ulasan.

LSA akan mematuhi kolom feedTimestampMicros dalam metadata untuk menjamin konsistensi data. Item feed dengan stempel waktu yang lebih lama akan dilewati untuk menghindari memperkenalkan keusangan jika item yang lebih baru yang memperbarui properti yang sama telah diproses. Partner bertanggung jawab untuk mencerminkan keaktualan data dengan benar menggunakan feedTimestampMicros di feed snapshot dan update.

Partner harus menggunakan Reporting API untuk mendapatkan informasi tentang prospek dan biaya per penyedia.