Penyedia pencarian web Windows Search

Windows Search saat ini menggunakan Web Search dari aplikasi Microsoft Bing untuk mengembalikan isi web dan hasil pencarian. Di Area Ekonomi Eropa (EEA), Anda dapat menginstal aplikasi yang mengimplementasikan penyedia pencarian web untuk mengembalikan konten web dan hasil pencarian di Windows Search.

Penyedia pencarian terintegrasi dengan pengalaman Pencarian dengan membuat paket MSIX dengan file manifes paket yang menyediakan informasi yang diperlukan bagi OS untuk mendaftarkan penyedia pencarian. Setelah penginstalan, penyedia pencarian diaktifkan secara default dalam pengalaman Pencarian Windows. Di aplikasi Pengaturan Windows, pengguna dapat mengaktifkan dan menonaktifkan penyedia pencarian yang diinstal dan mengelola urutan penyedia dalam hasil pencarian. Pengguna dapat menghapus penyedia pencarian melalui halaman Aplikasi > Pengaturan > terinstal di aplikasi Pengaturan Windows.

Untuk pengembangan dan pengujian, ketika Mode Pengembang diaktifkan dan aplikasi penyedia pencarian telah diunduh langsung pada perangkat, aplikasi tersebut akan muncul dalam daftar penyedia pencarian yang tersedia. Untuk informasi selengkapnya, lihat Mode Pengembang: fitur dan penelusuran kesalahan.

Setelah penyedia pencarian terdaftar dengan OS, kueri pengguna diteruskan ke titik akhir HTTP yang ditentukan oleh penyedia dalam manifes paket mereka menggunakan string kueri standar. Titik akhir mengembalikan hasil yang disarankan dalam dokumen JSON. Dengan setiap URL yang disarankan dalam dokumen respons, penyedia pencarian menyertakan URL titik akhir pratinjau, yang mengembalikan dokumen HTML yang ditampilkan di panel pratinjau di UI hasil pencarian.

Artikel ini menyediakan panduan untuk membuat paket aplikasi penyedia pencarian dan detail tentang protokol untuk menerapkan titik akhir HTTP penyedia pencarian.

Membuat paket aplikasi ekstensibilitas pencarian

Penyedia pencarian mendaftar dengan OS dengan menyediakan paket MSIX yang berisi informasi yang diperlukan tentang penyedia, seperti nama penyedia pencarian dan titik akhir HTTP untuk saran dan pratinjau.

Ekstensi aplikasi penyedia pencarian

File manifes paket aplikasi mendukung banyak ekstensi dan fitur yang berbeda untuk aplikasi Windows. Format manifes paket aplikasi didefinisikan oleh sekumpulan skema yang terdapat pada skema referensi manifes paket. Penyedia pencarian menyatakan informasi pendaftaran mereka dalam uap3:AppExtension. Atribut Nama ekstensi harus diatur ke "com.microsoft.windows.websearchprovider".

Penyedia pencarian harus menyertakan uap3:Properties sebagai anak dari uap3:AppExtension. Skema manifes paket tidak memberlakukan struktur elemen uap3:Properties selain memerlukan XML yang terbentuk dengan baik. Bagian lainnya menjelaskan format XML yang diharapkan OS agar berhasil mendaftarkan penyedia pencarian.

<uap3:Extension Category="windows.appExtension">
  <uap3:AppExtension Name="com.microsoft.windows.websearchprovider" DisplayName="SearchExampleApp" Id="ContosoSearchApp" PublicFolder="Public">
    <uap3:Properties>
    <!-- Search provider registration content goes here -->
    </uap3:Properties>
  </uap3:AppExtension>
</uap3:Extension>

Hierarki elemen

uap3:Properties

  Titik Akhir

  Protokol

Titik akhir

URL titik akhir HTTPS tempat OS akan mengirim permintaan kueri pencarian.

Protokol

Skema protokol yang akan digunakan saat meluncurkan hasil pencarian web yang disediakan. Jika protokol yang ditentukan tidak didaftarkan oleh aplikasi pada OS, maka browser default akan diluncurkan untuk hasil pencarian. Untuk informasi selengkapnya tentang mendaftarkan skema protokol, lihat uap:Protocol.

DynamicContentEndpoint

Fitur ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Menerapkan titik akhir ikon gleam. URL titik akhir HTTPS tempat OS akan mengirim permintaan agar ikon gleam ditampilkan di kotak pencarian.

Contoh file manifes paket

Berikut ini adalah contoh appmanifest.xml file manifes paket untuk mendaftarkan penyedia Pencarian Windows.

<!-- appxmanifest.xml -->

  <uap3:Extension Category="windows.appExtension">
	  <uap3:AppExtension Name="com.microsoft.windows.websearchprovider" DisplayName="CustomSearch" Id="CustomSearchApp" PublicFolder="Public">
		  <uap3:Properties>
			  <Endpoint>https://customsearchendpoint</Endpoint>
			  <Protocol>customsearch</Protocol>
        <DynamicContentEndpoint>https://sub.contoso.com/dynamic</DynamicContentEndpoint>
		  </uap3:Properties>
	  </uap3:AppExtension>
  </uap3:Extension>
  <uap:Extension Category="windows.protocol">
	  <uap:Protocol Name="customsearch"/>
  </uap:Extension>

Menerapkan titik akhir rekomendasi untuk penyedia Windows Search

Penyedia pencarian harus mengekspos dan mendaftarkan titik akhir HTTPS yang dipanggil oleh OS saat pengguna mengetik ke dalam kotak Pencarian Windows. Titik akhir ini harus mengembalikan string berformat JSON yang berisi saran pencarian untuk kueri pengguna yang disediakan. Konten harus dikirimkan melalui HTTPS. Integrasi pencarian tidak mendukung konten yang dikirimkan melalui HTTP.

Format permintaan HTTPS yang disarankan

Permintaan HTTPS ke titik akhir saran menggunakan format berikut.

https://contoso.com?setlang=en-US&cc=US&qry=

Parameter string kueri yang diteruskan ke titik akhir saran adalah sebagai berikut.

Pengaturan	Deskripsi
setlang	Lokasi terkait kueri
Cc	Kode negara yang terkait dengan kueri.
qry	Pertanyaan yang diberikan oleh pengguna. Jika parameter tidak memiliki nilai, yaitu muncul dalam string kueri sebagai qry=, maka kueri pengguna kosong. Penyedia pencarian masih dapat memberikan saran dan halaman pratinjau sebagai respons terhadap kueri kosong. NOTA OS tidak melakukan sanitasi string kueri apa pun. Penyedia pencarian dapat menerapkan sanitasi mereka sendiri saat kueri diterima.

Saran header respons HTTPS

Penyedia pencarian harus menyertakan header berikut dalam respons dari endpoint HTTPS sugesti.

• Access-Control-Allow-Origin: https://www.bing.com
• Access-Control-Allow-Credentials: benar
• Access-Control-Allow-Methods: GET
• Jenis Konten: aplikasi/json; charset=utf-8
• Panjang Konten: [Harus panjang respons yang tepat]

Format JSON tanggapan saran

Titik akhir HTTPS penyedia pencarian untuk saran harus mengembalikan dokumen JSON dengan format berikut. Nama kunci harus sama persis dengan format.

Kunci	Deskripsi
Saran	Berisi daftar objek JSON dengan kunci Attributes yang mewakili saran yang terkait dengan kueri pengguna.
Atributs	Berisi atribut dari saran.
URL	URL untuk saran pencarian di situs web penyedia.
kueri	Kueri pengguna yang terkait dengan saran pencarian.
previewPaneUrl	Alamat titik akhir untuk pratinjau dari mana pratinjau HTML dari saran dapat diambil.
Teks	Deskripsi teks saran.

{"Suggestions": 
   [{"Attributes": 
     {"url":"https://www.contoso.com/search?q=projection+matrix","query":"projection matrix","previewPaneUrl":"http://www.contoso.com/preview"} ,"Text":"projection matrix"}, 
    {"Attributes": 
     {"url":"https://www.contoso.com/search?q=rotation+matrix","query":"rotation matrix","previewPaneUrl":"http://www.contoso.com/preview"} ,"Text":"rotation matrix"}
    ] 
} 

Menerapkan titik akhir pratinjau penyedia Windows Search

Penyedia pencarian mengembalikan URL titik akhir HTTPS yang menyediakan pratinjau HTML halaman yang terkait dengan setiap saran dalam hasil pencarian. Respons titik akhir pratinjau harus mengembalikan kode HTML untuk halaman yang berfungsi.

Pratinjau format permintaan HTTPS

Permintaan HTTPS ke titik akhir pratinjau menggunakan format berikut.

https://contoso.com?Darkschemeovr=1

Parameter string kueri yang diteruskan ke titik akhir saran adalah sebagai berikut.

Pengaturan	Deskripsi
Darkschemeovr	Menentukan apakah sistem Windows panggilan mengaktifkan tema gelap. Nilainya adalah 1 jika tema gelap diaktifkan dan 0 jika tema gelap dinonaktifkan.

Pratinjau respons header HTTPS

• Access-Control-Allow-Origin: https://www.bing.com
• Access-Control-Allow-Credentials: benar
• Access-Control-Allow-Methods: GET
• Tipe Konten: teks/html; charset=utf-8
• Panjang Konten: [Harus panjang html pratinjau yang tepat]

Permintaan OPTIONS dan Berbagi Sumber Daya Lintas Asal (CORS)

Penyedia pencarian harus mendukung metode permintaan OPTIONS dan merespons permintaan ini dengan HTTP OK. Jika titik akhir penyedia pencarian menggunakan CORS, klien pencarian Windows akan mengirimkan permintaan HTTP OPTIONS sebelum setiap permintaan GET.

Menerapkan titik akhir ikon berkilau

Nota

Fitur gleam ini tidak lagi diaktifkan. Ikon Gleam tidak lagi ditampilkan untuk semua penyedia web di EEA. Konten di bagian dokumentasi ini sudah usang.

Penyedia pencarian dapat secara opsional menyediakan ikon kilap untuk mode terang dan mode gelap yang ditampilkan di bilah pencarian ketika penyedia pencarian sedang diaktifkan. Ketika elemen DynamicContentEndpoint disediakan dalam manifes aplikasi, permintaan akan dikirim ke URL yang ditentukan dan penyedia pencarian merespons dengan file json dalam format yang ditentukan di bawah ini yang mencakup URL file gambar ikon dan metadata lainnya. Permintaan ikon gleam akan dikirim secara berkala sementara penyedia pencarian adalah penyedia terbaru yang aktif di Windows Search. Frekuensi permintaan ini adalah setiap 6 jam. Permintaan juga akan dikirim pada setiap peluncuran Pencarian dan pada buka kunci perangkat.

Format Permintaan HTTPS untuk Ikon Gleam

Permintaan HTTPS ke titik akhir ikon cahaya menggunakan format berikut.

https://www.contoso.com/Gleam?cc=FR&setlang=en-us&dateTime=3%2F29%2F2024%2C%208%3A33%3A56%20PM&deviceOs=windows10&schemaversion=1.0.0

Parameter string kueri yang diteruskan ke titik akhir saran adalah sebagai berikut.

Pengaturan	Deskripsi
setlang	Lokasi terkait kueri
Cc	Kode negara yang terkait dengan kueri.
tanggalWaktu	Tanggal dan waktu saat ini dari perangkat klien, dikodekan dalam URL.
PerangkatOS	OS perangkat klien. Nilai parameter ini dapat berupa "Windows10" atau "Windows11". Pada Windows 10, ukuran ikon gleam adalah 30x60. Pada Windows 11, ukuran ikon gleam adalah 20x36
skemaversi	Versi skema gleam.

Format JSON untuk respons icon Gleam

Titik akhir HTTPS penyedia pencarian untuk ikon gleam harus mengembalikan dokumen JSON dengan format berikut. Nama kunci harus sama persis dengan format. Versi skema saat ini adalah 1.0.0.

Kunci	Deskripsi
skema versi	Versi skema gleam. Ini harus cocok dengan parameter string kueri schemaVersion dalam permintaan.
telemetryId	Pengidentifikasi unik untuk ikon gleam. Jika nilai dalam respons sama dengan nilai untuk ikon gleam saat ini, OS tidak akan memperbarui ikon.
waktu kedaluwarsa	Waktu kedaluwarsa untuk ikon gleam. Harus merupakan waktu di masa depan.
konten	Bagian konten respons.
kotakPencarianTaskbar	Berisi pengaturan untuk kotak pencarian.
berkilau	Berisi pengaturan untuk ikon gleam.
altText	Teks alternatif untuk ikon gleam.
dimensionEnum	Nilai "30x60" jika permintaan dikirim dari perangkat Windows 10. Nilai "20x36" jika permintaan dikirim dari perangkat Windows 11.
iconUrl	Berisi URL untuk berkas gambar ikon kilau terang dan gelap.
terang	URL untuk file gambar ikon cahaya berkilau.
gelap	URL untuk file gambar ikon kilau gelap.

{
  "schemaVersion":"1.0.0",
  "telemetryId":"<unique gleam Id>",
  "expirationTime":"2025-12-09T20:37:13Z",
  "content": {
    "taskbarSearchBox": {
      "gleam":{
        "altText": "<alt text of the gleam>",
        "dimensionEnum": "(30x60 for Windows 10, 20x36 for Windows 11)",
        "iconUrl": {
          "light":"<3p's light gleam url>",
          "dark": "<3p's dark gleam url>"
        }
      }
    }
  }
}

Validasi respons ikon Gleam

Respons harus menentukan URL aset terang dan URL aset gelap. Domain untuk URL gambar ikon harus menggunakan HTTPS dan subdomain harus cocok dengan subdomain yang ditentukan dalam elemen DynamicContentEndpoint dalam file manifes aplikasi.

File gambar harus dalam format SVG dan ukuran file maksimum adalah 300 kB. Kilau harus berada dalam bingkai berukuran 240x120px di dalam SVG.

Jika muatan kosong diterima, ikon gleam aktif akan dihapus dan tidak ada gleam yang akan ditampilkan.

Artikel terkait