# Algolia Source: https://developers.swell.is/app-guides/algolia The Algolia app keeps your Swell products in an Algolia index. Active products are sent to Algolia when they are created or edited, and removed when they are deactivated or deleted. A page in your Swell dashboard sends your whole catalog, or only the products created since a date, whenever you need to fill or refresh the index. The app doesn't add search to your storefront. Your storefront searches Algolia directly, for example with Algolia's InstantSearch library and a Search-Only API key. ## How it works | When | What the app does | | --- | --- | | An active product is created or edited | Sends the product to Algolia. The record with the same ID is replaced. | | A product is deactivated or deleted | Removes its record from Algolia. | | You run a sync from Products > Algolia sync | Sends all active products, or only those created on or after a date, one page at a time. | Automatic updates can be turned off with the **Sync product changes** setting. The sync page works either way. The app sends the same record fields as Swell's built-in Algolia integration. ## Before you begin - An Algolia account and application. Algolia creates the index the first time the app writes to it. - The application's **Application ID** and **Admin API Key**, from **Settings > API Keys** in the Algolia dashboard. The app needs the Admin API Key: the sync checks the key by listing your API keys, which a Search-Only or other restricted key cannot do. - If your store uses Swell's built-in Algolia integration, turn it off in **Integrations**. Running both sends every product to Algolia twice, and they overwrite each other's records if they use the same index. ## Set up Install Algolia from the Swell App Store, and set it up in your test environment before the live one. **1. Copy your Algolia keys** In the Algolia dashboard, go to **Settings > API Keys** and copy the **Application ID** and the **Admin API Key**. **2. Add the keys to the app** In Swell, go to **Apps > Algolia > Settings**, enter the **Application ID** and **Admin API Key**, and click **Save settings**. Products are sent to the `products` index. To use another index, enter its name in **Index Name**. **3. Sync your catalog** Go to **Products > Algolia sync**, choose **All products** and click **Start sync**. Keep the page open until it shows **Complete**. The first page checks your keys before any products are sent. **4. Test with a product** Edit an active product and save it. In the Algolia dashboard, search your index for the product. Its record ID is the Swell product ID, and the record shows your change. **5. Go live** Settings are saved separately for each environment. In the live environment, repeat steps 1 to 3 with the keys and index your storefront uses. Use a separate index, or a separate Algolia application, for the test environment, so testing doesn't change the index your storefront searches. ## Using Algolia ### Automatic updates - With **Sync product changes** on, products you create, edit, deactivate or delete are updated in Algolia within moments. - Inactive products are never sent. A product becomes searchable when you make it active. - Changes made while **Sync product changes** is off are not sent later. Run a sync to send them. ### Syncing products - **Products to sync:** **All products**, or **Products created on or after** a date. The date is the start of that day in your time zone. - **Page size:** 10, 100, 200, 500 or 1000 products per request. Larger pages need fewer requests. - Products are sent oldest first. The page shows a progress bar, how many products were processed and how many were sent to Algolia. - **Stop** finishes the page in progress, then stops. **Resume from page** continues a stopped or failed sync with the same products and page size. **Start new sync** starts over. - The sync runs in your browser, one page at a time, so keep the page open until it shows **Complete**. - Run a sync after bulk changes, such as an import, or after changing the index or the keys. ### Setting up search in Algolia The app sends product records. Searchable attributes, facets, ranking and synonyms are set in the Algolia dashboard. For category filters, use the `categories` attribute. For Algolia's hierarchical menu, use the category level attributes. See **For developers** below for the record fields. ### In the dashboard | Location | What it shows | | --- | --- | | Products > Algolia sync | The sync page: products to sync, page size, progress, and the details of any error. | | Apps > Algolia > Settings | Your Algolia keys, the index name and the Sync product changes switch. | ## Settings Settings are in **Apps > Algolia > Settings** and are saved separately for each environment. | Setting | Description | Default | | --- | --- | --- | | Application ID | ID of your Algolia application. Required. | None | | Admin API Key | Admin API Key of the application. Required. Used only on Swell's servers to write to the index, and never sent to the browser. | None | | Index Name | Algolia index that receives the product records. An empty value uses products. | products | | Sync product changes | Sends product creates, edits and deletes to Algolia as they happen. The sync page works either way. | On | ## Limitations - The app doesn't add search to your storefront. - Only active products are indexed, one record per product. Variants, categories and content pages are not indexed as their own records. - A sync replaces existing records but doesn't delete records of products that no longer exist in Swell, such as products deleted while **Sync product changes** was off. To clean up the index, clear it in Algolia, then sync all products. - The app doesn't configure searchable attributes, facets or ranking. - Algolia's plan limits apply, including the maximum record size and monthly operations. Every automatic update and every synced product counts as an operation. ## Troubleshooting ### The sync fails with "Invalid Application-ID or API key" The keys don't work, or the key is not the Admin API Key. Copy the **Application ID** and **Admin API Key** again from **Settings > API Keys** in Algolia, save the settings and start the sync again. ### The sync fails with "Missing Algolia Application ID or Admin API Key in app settings" Enter both keys in **Apps > Algolia > Settings** and click **Save settings**. ### The error says the key has "not enough rights" The key can't write to the index. Use the Admin API Key, or a key with write access to the index. ### A sync stops partway with an error Open **Error details** under the error. It shows the step that failed, the HTTP status and the response. Fix the cause, then click **Resume from page**. If records are too large for a page, start a new sync with a smaller page size. ### A product change doesn't show in Algolia Check that **Sync product changes** is on, that both keys are set, and that the product is active. Then save the product again, or run a sync of the products created on or after its creation date. ### Deleted or deactivated products still show in search Products deleted or deactivated while **Sync product changes** was off are not removed by a sync. Clear the index in Algolia, then sync all products. ### The sync page asks you to open it from the Swell dashboard The page works only inside the Swell dashboard, signed in to the store it syncs. Open it from **Products > Algolia sync**. ## Uninstalling Uninstalling the app stops automatic updates and removes **Algolia sync** from the Products menu. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately. Uninstalling doesn't change your Algolia index. The records the app sent stay there until you delete them in Algolia. ## For developers The app adds no fields to Swell records. Each active product becomes one Algolia record: | Field | Description | | --- | --- | | objectID | The Swell product ID. | | name, description, content, meta_description, slug | Product fields, as in Swell. | | price, orig_price, currency, sku | Product price fields and SKU. | | images | Product images, with id, caption, and the file url, width and height. | | stock_status, stock_tracking, stock_purchasable | Product stock fields. | | attributes | Product attributes. | | bundle, bundle_items | For bundles, the quantity and name of each bundled product. | | categories | The full path of every category the product is in, for category filters. | | lvls | Levels (lvl0, lvl1, and so on) of each nested category path, named after the category, for the hierarchical menu. | | _ | Localized values when the store has more than one language, for example name_fr. meta_title, meta_description and tags are then left out. | Category paths keep the spacing of the built-in integration, for example `Clothing > Shirts` . Fields with empty, zero or false values are left out of the record. Automatic updates run in a function on the `product.created`, `product.updated` and `product.deleted` events. Algolia errors with a 4xx status, such as a wrong key or an oversized record, are not retried. 5xx and network errors are retried. The private route `/functions/algolia/sync-products` sends one page of products, the same as the sync page. Call it with `page`, and optionally `limit` and `created_after`, then with the next page until the response has `done: true`. This writes to Algolia. ```sh swell api post /functions/algolia/sync-products --body '{"page": 1, "limit": 100}' ``` The response has `page`, `limit`, `count`, `synced` and `done`. ## Support Swell builds and maintains the Algolia app. For help with the app, email support@swell.is. For questions about your Algolia account, plan or search setup, contact Algolia.