웹페이지에 검색 위젯을 추가하기 전에 검색 위젯의 결과 구성부터 시작하여 검색 위젯을 구성해야 합니다. 웹페이지에서 검색 위젯의 스타일을 조정할 수는 없습니다.
절차
웹페이지에 검색 위젯을 추가하는 절차는 선택한 승인 유형에 따라 다릅니다.
승인 토큰: 위젯은 코드베이스에서 제공하는 JWT 또는 OAuth 토큰을 사용합니다. 토큰을 생성하는 데 사용할 수 있는 자체 서버가 있어야 합니다. 인증 토큰은 사용자 또는 서비스 계정을 대신하여 API를 호출하는 데 사용됩니다. 인증 토큰을 생성할 때는 OAuth 범위 https://www.googleapis.com/auth/cloud-platform을 사용합니다.
예를 들어 위젯을 페이지 example.com/ai.html 및 cymbal.example.com/search.html에 복사하려면 example.com을 도메인으로 입력합니다. 하위 도메인의 페이지에서만 위젯이 작동하도록 하려면 cymbal.example.com을 입력합니다.
localhost에서 위젯을 테스트하려면 localhost을 입력합니다.
추가를 클릭합니다.
위젯이 표시될 도메인마다 6단계를 반복합니다.
저장을 클릭합니다.
웹 애플리케이션에 다음 코드 복사 섹션에 제공된 코드 스니펫을 복사합니다.
선택사항: 검색 위젯 동작을 맞춤설정하려면 다음을 변경합니다.
웹의 결과를 새 탭에서 대신 열려면 복사된 코드 스니펫에 다음을 추가하세요. 기본적으로 구조화되지 않은 문서의 결과는 새 탭에서 열리고 웹의 결과는 위젯과 동일한 페이지에서 열립니다.
anchorsTarget="_blank"
예를 들면 다음과 같습니다.
<gen-search-widget configId="..." anchorsTarget="_blank"></gen-search-widget>
검색창 내의 자리표시자 텍스트를 맞춤설정하려면 복사된 코드 스니펫에 다음을 추가하세요.
placeholder="CUSTOM_PLACEHOLDER"
예를 들면 다음과 같습니다.
<gen-search-widget configId="..." placeholder="Start your search here"></gen-search-widget>
트리거 없이 항상 위젯을 표시하려면 복사한 코드 스니펫에 다음을 추가하세요.
alwaysOpened
예를 들면 다음과 같습니다.
<gen-search-widget alwaysOpened></gen-search-widget>
코드베이스에서 승인 토큰을 생성합니다.
위젯에 승인 토큰을 전달하려면 다음 코드를 웹 애플리케이션에 복사 섹션에 제공된 두 번째 코드 스니펫인 "// Set authorization token"을 사용하고 <JWT or OAuth token
provided by you backend> 텍스트를 승인 토큰으로 바꿉니다.
공개 액세스의 경우 검색 앱이 액세스 제어의 데이터 스토어와 연결되어 있지 않은지 확인합니다.
통합을 클릭합니다.
위젯 탭을 클릭합니다.
위젯 승인 유형으로 공개 액세스를 선택합니다.
위젯 페이지의 도메인 이름을 지정합니다.
위젯이 표시될 페이지의 도메인 이름을 입력합니다.
예를 들어 위젯을 페이지 example.com/ai.html 및 cymbal.example.com/search.html에 복사하려면 example.com을 도메인으로 입력합니다. 하위 도메인의 페이지에서만 위젯이 작동하도록 하려면 cymbal.example.com을 입력합니다.
localhost에서 위젯을 테스트하려면 localhost을 입력합니다.
추가를 클릭합니다.
위젯이 표시될 도메인마다 6단계를 반복합니다.
저장을 클릭합니다.
웹 애플리케이션에 다음 코드 복사 섹션에 제공된 코드 스니펫을 복사합니다.
선택사항: 검색 위젯 동작을 맞춤설정하려면 다음을 변경합니다.
웹의 결과를 새 탭에서 대신 열려면 복사된 코드 스니펫에 다음을 추가하세요. 기본적으로 구조화되지 않은 문서의 결과는 새 탭에서 열리고 웹의 결과는 위젯과 동일한 페이지에서 열립니다.
anchorsTarget="_blank"
예를 들면 다음과 같습니다.
<gen-search-widget configId="..." anchorsTarget="_blank"></gen-search-widget>
검색창 내의 자리표시자 텍스트를 맞춤설정하려면 복사된 코드 스니펫에 다음을 추가하세요.
placeholder="CUSTOM_PLACEHOLDER"
예를 들면 다음과 같습니다.
<gen-search-widget configId="..." placeholder="Start your search here"></gen-search-widget>
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-05(UTC)"],[[["\u003cp\u003eThis page provides instructions on how to integrate a search widget into your website, enabling search functionality for your users.\u003c/p\u003e\n"],["\u003cp\u003eBefore adding the widget, you must first configure the search widget attributes, but note that you can not modify the styling of the widget.\u003c/p\u003e\n"],["\u003cp\u003eThere are two authorization methods for the search widget: using an authorization token (JWT or OAuth) or public access, with the token method requiring a server to generate the token and public access not restricting results.\u003c/p\u003e\n"],["\u003cp\u003eAdding the widget involves selecting the authorization type, specifying the domains where the widget will appear, and then copying and pasting the provided code snippet into your webpage.\u003c/p\u003e\n"],["\u003cp\u003eIf using an authorization token, you must also include a separate code snippet in your website's code to pass the token to the widget, as well as periodically refresh it, and an optional parameter can be added to make the web results open in new tabs.\u003c/p\u003e\n"]]],[],null,["# Add the search widget to a web page\n\nThis page describes how to add search functionality to a website using the\nsearch widget.\n\nBefore you begin\n----------------\n\nBefore you add a search widget to your web page, be sure to configure your\nsearch widget, starting with [Configure results for the search\nwidget](/generative-ai-app-builder/docs/configure-widget-attributes). Note that it's not possible to adjust the\nstyling of the search widget in your web page.\n\nProcedures\n----------\n\nThe procedure for adding the search widget to your web page differs depending on\nthe authorization type you choose:\n\n- **Authorization token** : The widget uses a JWT or OAuth token provided by\n your codebase. You must have your own server that you can use to generate a\n token. The auth token is used to make an API call on behalf of the user or\n service account. When generating the auth token, use the OAuth scope\n `https://www.googleapis.com/auth/cloud-platform`.\n\n - **For server-to-server interactions with service accounts:** See [Using OAuth\n 2.0 for Server to Server\n Applications](https://developers.google.com/identity/protocols/oauth2/service-account)\n in the authorization documentation.\n\n - **For JavaScript web applications:** See [OAuth 2.0 for Client-side Web\n Applications](https://developers.google.com/identity/protocols/oauth2/javascript-implicit-flow)\n in the authorization documentation.\n\n | **Note:** If you selected a workforce pool to control access to your app's data, then [obtain short-lived tokens for workforce identity\n | federation](/iam/docs/workforce-obtaining-short-lived-credentials).\n- **Public access**: The widget won't restrict who can get results from a\n search query.\n\n### Add a widget that uses an authorization token\n\n1. In the Google Cloud console, go to the **AI Applications** page.\n\n [AI Applications](https://console.cloud.google.com/gen-app-builder/start)\n2. Click the name of the app that you want to edit.\n\n3. Click **Integration**.\n\n4. Click the **Widget** tab.\n\n5. Select **JWT or OAuth based** as the widget authorization type.\n\n6. Specify the domain name for the widget page:\n\n 1. Enter the domain name for the page where the widget will appear.\n\n For example, if you are going to copy the widget to the pages\n `example.com/ai.html` and `cymbal.example.com/search.html`, enter\n `example.com` as the domain. If you only want the widget to work on a page\n in the subdomain, enter `cymbal.example.com`.\n\n If you want to test the widget on your localhost, enter `localhost`.\n 2. Click **Add**.\n\n7. Repeat step 6 for each domain where the widget will appear.\n\n8. Click **Save**.\n\n9. Copy the code snippet provided in the **Copy the following code to your\n web application** section.\n\n10. Optional: Make the following changes to customize the search widget\n behavior:\n\n - To open the results from the web in new tabs instead, add the following\n to the copied code snippet. By default, results from unstructured\n documents open in new tabs, while results from the web open in the same\n page as the widget.\n\n anchorsTarget=\"_blank\"\n\n For example:\n `\u003cgen-search-widget configId=\"...\" anchorsTarget=\"_blank\"\u003e\u003c/gen-search-widget\u003e`\n - To customize the placeholder text inside the search bar, add the following\n to the copied code snippet:\n\n placeholder=\"\u003cvar translate=\"no\"\u003eCUSTOM_PLACEHOLDER\u003c/var\u003e\"\n\n For example:\n `\u003cgen-search-widget configId=\"...\" placeholder=\"Start your search here\"\u003e\u003c/gen-search-widget\u003e`\n - To always show the widget without a trigger, add the following\n to the copied code snippet:\n\n alwaysOpened\n\n For example:\n `\u003cgen-search-widget alwaysOpened\u003e\u003c/gen-search-widget\u003e`\n11. In your codebase, generate an authorization token.\n\n | **Note:** If you selected a workforce pool to control access to your app's data, then [obtain short-lived tokens for workforce identity federation](/iam/docs/workforce-obtaining-short-lived-credentials).\n12. To pass the authorization token to your widget, use the second code snippet,\n \"`// Set authorization token`\", provided in the **Copy the following code\n to your web application** section and replace the text `\u003cJWT or OAuth token\n provided by you backend\u003e` with your authorization token.\n\n13. Periodically set a fresh token by repeating the previous step before the\n current token expires.\n\n### Add a widget that has public access\n\n| **Note:** If your organization requires VPC Service Controls enforcement to protect data, then don't use public access for widget authorization.\n\n1. In the Google Cloud console, go to the **AI Applications** page.\n\n [AI Applications](https://console.cloud.google.com/gen-app-builder/start)\n2. Click the name of the app that you want to edit.\n\n For public access, make sure that the search app isn't associated with any\n data store under [access control](/generative-ai-app-builder/docs/data-source-access-control).\n3. Click **Integration**.\n\n4. Click the **Widget** tab.\n\n5. Select **Public Access** as the widget authorization type.\n\n6. Specify the domain name for the widget page:\n\n 1. Enter the domain name for the page where the widget will appear.\n\n For example, if you are going to copy the widget to the pages\n `example.com/ai.html` and `cymbal.example.com/search.html`, enter\n `example.com` as the domain. If you only want the widget to work on pages\n in the subdomain, enter `cymbal.example.com`.\n\n If you want to test the widget on your localhost, enter `localhost`.\n 2. Click **Add**.\n\n7. Repeat step 6 for each domain where the widget will appear.\n\n8. Click **Save**.\n\n9. Copy the code snippet provided in the **Copy the following code to your\n web application** section.\n\n10. Optional: Make the following changes to customize the search widget\n behavior:\n\n - To open the results from the web in new tabs instead, add the following\n to the copied code snippet. By default, results from unstructured\n documents open in new tabs, while results from the web open in the same\n page as the widget.\n\n anchorsTarget=\"_blank\"\n\n For example:\n `\u003cgen-search-widget configId=\"...\" anchorsTarget=\"_blank\"\u003e\u003c/gen-search-widget\u003e`\n - To customize the placeholder text inside the search bar, add the following\n to the copied code snippet:\n\n placeholder=\"\u003cvar translate=\"no\"\u003eCUSTOM_PLACEHOLDER\u003c/var\u003e\"\n\n For example:\n `\u003cgen-search-widget configId=\"...\" placeholder=\"Start your search here\"\u003e\u003c/gen-search-widget\u003e`\n - To always show the widget without a trigger, add the following\n to the copied code snippet:\n\n `\u003cgen-search-widget alwaysOpened\u003e\u003c/gen-search-widget\u003e`\n11. Paste the code snippet into your web page.\n\nExample of an embedded public-access widget\n-------------------------------------------\n\nTo see a search widget embedded in a public webpage, see the\n[Try Vertex AI Search](/generative-ai-app-builder/docs/try-it) page.\nThe Try Vertex AI Search search widget\n\n\u003cbr /\u003e\n\nThis search widget works with the following configuration: \n\n \u003cgen-search-widget\n configId=\"123456\"\n anchorsTarget=\"_blank\"\n placeholder=\"Search something about AI Applications\"\n alwaysOpened\u003e\n \u003c/gen-search-widget\u003e"]]
