{"id":19924382,"url":"https://github.com/kontent-ai/integration-example-algolia","last_synced_at":"2025-05-03T07:31:29.012Z","repository":{"id":43261241,"uuid":"342198655","full_name":"kontent-ai/integration-example-algolia","owner":"kontent-ai","description":"Example implementation of integration between Algolia search engine and Kontent.ai.","archived":false,"fork":false,"pushed_at":"2024-09-16T17:49:03.000Z","size":8278,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-04-07T13:11:13.999Z","etag":null,"topics":["algolia","hacktoberfest","headless-cms","integration","kontent-ai","kontent-ai-integration","search"],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kontent-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-25T09:58:13.000Z","updated_at":"2024-07-10T12:58:39.000Z","dependencies_parsed_at":"2024-07-09T21:46:43.293Z","dependency_job_id":null,"html_url":"https://github.com/kontent-ai/integration-example-algolia","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fintegration-example-algolia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fintegration-example-algolia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fintegration-example-algolia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fintegration-example-algolia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kontent-ai","download_url":"https://codeload.github.com/kontent-ai/integration-example-algolia/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252156909,"owners_count":21703371,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algolia","hacktoberfest","headless-cms","integration","kontent-ai","kontent-ai-integration","search"],"created_at":"2024-11-12T22:17:12.953Z","updated_at":"2025-05-03T07:31:24.002Z","avatar_url":"https://github.com/kontent-ai.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Core integration][core-shield]](https://kontent.ai/integrations/algolia)\n\n![Last modified][last-commit]\n[![Issues][issues-shield]][issues-url]\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![MIT License][license-shield]][license-url]\n\n[![Stack Overflow][stack-shield]](https://stackoverflow.com/tags/kontent-ai)\n[![Discord][discord-shield]](https://discord.gg/SKCxwPtevJ)\n\n\u003cp align=\"center\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/kai-logo-hor-neg-rgb.svg\"\u003e\n  \u003cimg alt=\"Kontent.ai logo for dark/light scheme.\" src=\"docs/kai-logo-hor-pos-rgb.svg\" width=\"300\"\u003e\n\u003c/picture\u003e\n\u003cimage src=\"docs/algolia-logo.png\" alt=\"algolia logo\" width=\"300\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#demo\"\u003eDemo\u003c/a\u003e •\n  \u003ca href=\"#prerequisities\"\u003ePrerequisities\u003c/a\u003e •\n  \u003ca href=\"#get-started\"\u003eGet started\u003c/a\u003e •\n  \u003ca href=\"#search-data-structure\"\u003eSearch data structure\u003c/a\u003e •\n  \u003ca href=\"#developing\"\u003eDeveloping\u003c/a\u003e •\n  \u003ca href=\"#contributors\"\u003eContributors\u003c/a\u003e •\n  \u003ca href=\"#license\"\u003eLicense\u003c/a\u003e •\n  \u003ca href=\"#additional-resources\"\u003eResources\u003c/a\u003e\n\u003c/p\u003e\n\nThis repository contains an _example implementation_ of integration between [Algolia](https://www.algolia.com/) search engine and [Kontent.ai](https://kontent.ai/). It produces an optional [custom element](https://kontent.ai/learn/tutorials/develop-apps/integrate/content-editing-extensions) for indexing your content in Algolia with a search preview functionality, as well as **two** [Netlify functions](https://docs.netlify.com/functions/overview/) for the **initial setup** and subsequent **processing of content changes** via a [webhook](https://kontent.ai/learn/tutorials/develop-apps/integrate/webhooks).\n\nThis implementation also supports **tracking changes in [linked content](https://kontent.ai/learn/tutorials/write-and-collaborate/structure-your-content/link-related-content-together)**, as well as **searching in multiple languages**.\n\n## Demo\n\n![algolia-custom-element](docs/algolia-element.gif)\n\n## Prerequisities\n\n1. To run this integration, you'll need a Kontent.ai project + Algolia account.\n2. The content you want to be returned upon searching has to contain some kind of universal **[slug property](https://itnext.io/whats-a-slug-f7e74b6c23e0)** (of any type). (_Kontent.ai supports a [SEO-friendly way to work with URLs](https://kontent.ai/learn/tutorials/develop-apps/optimize-your-app/seo-friendly-urls) through URL slugs_).\n\n## Get Started\n\n1. ### Quick Deploy\n   Netlify has made this easy. If you click the deploy button below, it will guide you through the process of deploying it to Netlify and leave you with a copy of the repository in your account as well.\n\n   [![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/kontent-ai/integration-example-algolia)\n\n   After you deploy the project into Netlify, you'll find two functions there:\n   ![netlify-functions](docs/netlify-functions.png)\n   1. **algolia-init-function** is the function that indexes or refreshes all of your content from Kontent.ai into Algolia.\n   2. **algolia-update-webhook** is the function you want to call via a webhook from Kontent.ai to notify Algolia there's been a change to your content and that it has to be updated and how.\n\n2. ### Create a new Webhook in Kontent.ai\n   The next step is [creating a new webhook in Kontent.ai](https://kontent.ai/learn/docs/webhooks/webhooks/javascript#a-create-webhooks).\n\n   Fill out the following into the webhook's **URL address** field:\n\n   {**algolia-update-webhook endpoint URL**}?appId={**algolia application id**}\u0026index={**algolia search index name**}\u0026slug={**codename of content's slug property**}\n\n   Subsequently, set the Kontent.ai **Delivery API triggers** to watch for changes in _published data_ on _content item events_.\n\n   At the end, this is an example of how your webhook might look like:\n\n   ![webhook-setup](docs/webhook.png)\n\n   Save the webhook and copy the generated **secret** as it would be required as a parameter in the following step.\n\n3. ### Configure your Netlify functions\n\n   To **setup** both function, all you need to do is set the following **[environment variables](https://docs.netlify.com/configure-builds/environment-variables/)** for your Netlify site.\n\n   | Variable        | Value                                                                                                                                  |\n   | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n   | ALGOLIA_API_KEY | your [Algolia Admin key](https://www.algolia.com/doc/guides/security/api-keys/#admin-api-key)                                          |\n   | KONTENT_SECRET  | your [Kontent.ai webhook secret](https://kontent.ai/learn/tutorials/develop-apps/integrate/webhooks#a-validate-received-notifications) |\n\n   The Algolia admin key is used by the function to create/recreate your search index, as well as for indexing your content.\n\n   The Kontent.ai webhook secret is used to ensure integrity of the webhook payload. It has been created in the previous step.\n\n   After your function has been redeployed (or your environment variables has been propagated), the functions are ready to be called.\n\n   You can observe the real-time **Function log** on the same screen you'd find your function's endpoint (_Functions_ -\u003e _your function_).\n\n4. ### Run the index initialization\n   The initialization of your Algolia index with your content is done through the **algolia-init-function**. Simply make a POST request towards the function's endpoint URL with the following payload:\n\n   https://github.com/kontent-ai/integration-example-algolia/blob/074f1c02c9d13a3e290a9f75aa3d90a697a3ce0c/src/shared/constants/readmeSnippets.ts#L15-L21\n\n   The function processes all **published** content from your project (based on the given ID) and creates or updates the search index in Algolia (again, based on the given parameter).\n\n   Alternatively, you can use the **custom element** that is a part of this repository as well.\n\n   Simply add a new [custom element](https://kontent.ai/learn/tutorials/develop-apps/integrate/content-editing-extensions) into your content model (it might be a good idea to create some kind of _meta_ content type to store some of the project's settings, so that would be a good place to put this element as well).\n\n   Use your netlify's URL for the base page as the **Hosted code URL** and a following settings to setup the custom element:\n\n   https://github.com/kontent-ai/integration-example-algolia/blob/074f1c02c9d13a3e290a9f75aa3d90a697a3ce0c/src/shared/constants/readmeSnippets.ts#L6-L13\n\n   The [Algolia's search-only api key](https://www.algolia.com/doc/guides/security/api-keys/#search-only-api-key) is used to preview the search functionality from within the custom element.\n\n   The custom element allows you to (re)initialize your Algolia index with all of your content + offers a way to preview your search results.\n   \u003ca href=\"#demo\"\u003e **Check out the demo gif above!**\u003c/a\u003e\n\n   If you are working with content in [multiple language variants](https://kontent.ai/learn/tutorials/write-and-collaborate/create-multilingual-content/translate-content-items), adding additional variants to your search index is just as easy as just simply switching to the desired variant and activating the custom element to sync all content of the selected variant.\n\n## Search data structure\n\nWhen building your search UI, you'll need to understand how the data is being stored inside of your Algolia search index. You can see an example of a content item with slug (i.e. separate \"page\"), that is linked to a Homepage page and contains its own content, as well as two linked items.\n\n![algolia-data](docs/algolia-data.png)\n\nYou can explore your own generated index to figure out how to implement your search, as well as the code of this custom element that is already implementing a preview of the search functionality [here](src/algolia-sync.js).\n\n## Developing\n\n[Netlify Dev](https://www.netlify.com/products/dev/) is highly recommended for local development.\n\n```bash\n# Initial project setup\n$ npm ci\n\n# Build the project\n$ npm run build\n```\n\nThe integration is created with [Vite](https://vitejs.dev/).\n\n## Contributors\n\nWe have collected notes on how to contribute to this project in [CONTRIBUTING.md](CONTRIBUTING.md).\n\n\u003ca href=\"https://github.com/kontent-ai/integration-example-algolia/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=kontent-ai/integration-example-algolia\" /\u003e\n\u003c/a\u003e\n\n## License\n\n[MIT](https://tldrlegal.com/license/mit-license)\n\n## Additional Resources\n\n- [Kontent.ai Integration documentation](https://kontent.ai/learn/tutorials/develop-apps/integrate/integrations-overview)\n\n[last-commit]: https://img.shields.io/github/last-commit/kontent-ai/integration-example-algolia?style=for-the-badge\n[contributors-shield]: https://img.shields.io/github/contributors/kontent-ai/integration-example-algolia.svg?style=for-the-badge\n[contributors-url]: https://github.com/kontent-ai/integration-example-algolia/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/kontent-ai/integration-example-algolia.svg?style=for-the-badge\n[forks-url]: https://github.com/kontent-ai/integration-example-algolia/network/members\n[stars-shield]: https://img.shields.io/github/stars/kontent-ai/integration-example-algolia.svg?style=for-the-badge\n[stars-url]: https://github.com/kontent-ai/integration-example-algolia/stargazers\n[issues-shield]: https://img.shields.io/github/issues/kontent-ai/integration-example-algolia.svg?style=for-the-badge\n[issues-url]: https://github.com/kontent-ai/integration-example-algolia/issues\n[license-shield]: https://img.shields.io/github/license/kontent-ai/integration-example-algolia.svg?style=for-the-badge\n[license-url]: https://github.com/kontent-ai/integration-example-algolia/blob/master/LICENSE\n[core-shield]: https://img.shields.io/static/v1?label=\u0026message=core%20integration\u0026style=for-the-badge\u0026color=FF5733\n[stack-shield]: https://img.shields.io/badge/Stack%20Overflow-ASK%20NOW-FE7A16.svg?logo=stackoverflow\u0026logoColor=white\u0026style=for-the-badge\n[discord-shield]: https://img.shields.io/discord/821885171984891914?label=Discord\u0026logo=Discord\u0026logoColor=white\u0026style=for-the-badge\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkontent-ai%2Fintegration-example-algolia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkontent-ai%2Fintegration-example-algolia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkontent-ai%2Fintegration-example-algolia/lists"}