> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/ai-powered-search/installation-and-integration.md).

# Installation & Integration

In modern e-commerce, users rarely type perfect queries. They abbreviate, misspell, and switch languages mid-search. AI Powered Search is built to handle exactly that: a user typing "man tshirt red cheap" gets results filtered by gender, color, and sorted by price — without any manual rule configuration. It combines a rule-based search plan engine with a large language model to extract facets, sorters, and normalized search text from freeform input, then routes the query to the right result set.

AI Powered Search is not a black box. Through Omnitron, teams can see what users are searching for and how often, approve or adjust AI-generated search plans, and identify which queries are driving traffic. This happens across four screens: Dashboard (activity overview and search volume trends), Search Results (raw search terms and their frequency), Keywords (grouping searches into structured signals), and Search Plans (defining the filters, sorters, and query logic each keyword triggers).

This guide covers everything needed to adopt AI Powered Search on an Akinon Commerce Cloud project, in four parts: Part 1 installs it from the ACC App Store, Part 2 retrieves its application URL, and Parts 3 and 4 integrate that URL into the storefront — for Next.js and Django (Omnife/Akinon) projects respectively. Work through them in order, or jump to the integration part that matches your stack.

### <mark style="color:red;">AI Powered Search — Installation Guide</mark>

#### <mark style="color:red;">Overview</mark>

AI Powered Search is an AI-powered application available through the Akinon Commerce Cloud (ACC) App Store. This guide walks you through installing AI Powered Search on your Commerce Cloud project.

#### <mark style="color:red;">Prerequisites</mark>

Before you begin, ensure you have the following:

* An active Akinon Commerce Cloud (ACC) account with access to the App Store
* Access to the Omnitron panel for your project

#### <mark style="color:red;">Quick Start</mark>

* Search for **Samanlik AI** in the ACC App Store.
* Select your project and configure the required fields.
* Click **Install** to complete the installation.

#### <mark style="color:red;">Installation Steps</mark>

**Step 1 — Find Samanlik AI in the App Store**

* Open the ACC App Store. For detailed instructions on navigating the App Store, see the [ACC App Store](/tutorials/acc/how-to-install-applications-from-the-app-store-in-acc.md) guide.
* In the *Application Name* field, type **Samanlik AI** and press **Search**.

<figure><img src="/files/joojYurmsFIjmRjh0rP6" alt=""><figcaption></figcaption></figure>

* Click **Samanlik AI** in the results list.

**Step 2 — Select Your Project**

* Select the project you want to install AI Powered Search on.

<figure><img src="/files/skdEco9jwWo3mJknI8f4" alt=""><figcaption></figcaption></figure>

* Click **Configure Application Values**.

<figure><img src="/files/LU2HgIQcZV3Q7fOUAcEm" alt=""><figcaption></figcaption></figure>

**Step 3 — Configure Required Fields**

Fill in the following required fields:

<table data-header-hidden><thead><tr><th valign="middle"></th><th valign="middle"></th></tr></thead><tbody><tr><td valign="middle"><strong>Field</strong></td><td valign="middle"><strong>Description</strong></td></tr><tr><td valign="middle">COMMERCE_APP_URL</td><td valign="middle">The URL of your Commerce application</td></tr><tr><td valign="middle">OMNITRON_CHANNEL_ID</td><td valign="middle">The channel ID of your Sales Channel in Omnitron</td></tr></tbody></table>

<figure><img src="/files/f7ujsKLQd9CvhGFLefv2" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
`OMNITRON_USERNAME` and `OMNITRON_PASSWORD` are optional feature fields. You do not need to fill them in for a standard installation.
{% endhint %}

**How to Find COMMERCE\_APP\_URL**

* Go to the Commerce Cloud Projects page.

<figure><img src="/files/yvg3tV9N2dLdZbh80ncN" alt=""><figcaption></figcaption></figure>

• Select your project.

<figure><img src="/files/C4CAP9UXWyYl2aI6fyen" alt=""><figcaption></figcaption></figure>

• Click the **Commerce** application.

<figure><img src="/files/QP3w73P0sn6kkq24QsfV" alt=""><figcaption></figcaption></figure>

• Copy the application URL displayed on the page.

<figure><img src="/files/u1Dv5d1NGaQhXr4oONKB" alt=""><figcaption></figcaption></figure>

* Paste it into the `COMMERCE_APP_URL` field.

**How to Find `OMNITRON_CHANNEL_ID`**

{% hint style="info" %}
For detailed information on configuring Sales Channels, see the [Omnitron Sales Channel ](/tutorials/omnitron/settings/how-to-add-and-configure-a-new-sales-channel-in-omnitron.md)guide.
{% endhint %}

* Open the Omnitron panel.
* Navigate to **Settings > Sales Channels**.
* Locate the Sales Channel you want to use.

<figure><img src="/files/oXe5l55TUMm2Gr6O3lu6" alt=""><figcaption></figcaption></figure>

* Copy its ID and paste it into the `OMNITRON_CHANNEL_ID` field.

**Step 4 — Save and Continue**

* After filling in `COMMERCE_APP_URL` and `OMNITRON_CHANNEL_ID`, click **Save and Continue**.

<figure><img src="/files/cJ3sl28l75VsPthNlMUZ" alt=""><figcaption></figcaption></figure>

**Step 5 — Install**

* On the Install page, verify the **Project Name** and **Application Values**,

<figure><img src="/files/cgccXK1PdBkjuAhdsbj2" alt=""><figcaption></figcaption></figure>

• Click **Install**.

<figure><img src="/files/NRQhB6OkiJxToHOujtzi" alt=""><figcaption></figcaption></figure>

#### <mark style="color:red;">**Verification**</mark>

After installation, verify that AI Powered Search is running correctly using the following methods.

**Frontend Integration**

To use AI Powered Search on your storefront, integrate it into your project by referencing the following files:

{% hint style="info" %}
Next.js integration: see Part 3 — “AI Powered Search — Installation & Integration (Next.js)” of this document. Django integration: see Part 4 — “Installation & Integration (Django)” of this document.
{% endhint %}

#### <mark style="color:red;">API Health Check</mark>

Send the following request to confirm the API is responding:

```json
curl -X GET \
  'https://{SAMANLIK_AI_BASE_URL}/api/v1/ner?search_text=test' \
  -H 'accept: application/json'
```

A successful 200 OK response confirms that AI Powered Search is operational.

### <mark style="color:red;">Accessing the AI Powered Search Application URL</mark>

With AI Powered Search installed and verified in Part 1, the next thing you need is the application URL it exposes — the endpoint your storefront calls at runtime. This part shows where to find and copy that URL in Commerce Cloud.

#### <mark style="color:red;">Overview</mark>

This part explains how to locate the AI Powered Search application URL in Commerce Cloud. You use this URL when configuring the frontend integration.

{% hint style="info" %}
If AI Powered Search is not yet installed on your project, complete the installation steps first. See Part 1 — “AI Powered Search — Installation Guide” of this document.
{% endhint %}

#### <mark style="color:red;">Prerequisites</mark>

* An active Commerce Cloud account with access to the relevant project.
* AI Powered Search installed on the project. See Part 1 — “AI Powered Search — Installation Guide” of this document.

#### <mark style="color:red;">Steps</mark>

* Log in to [Commerce Cloud](https://console.akinoncloud.com/auth/login/).
* Navigate to Projects.

<figure><img src="/files/yvg3tV9N2dLdZbh80ncN" alt=""><figcaption></figcaption></figure>

• Select the project where AI Powered Search is installed.

<figure><img src="/files/C4CAP9UXWyYl2aI6fyen" alt=""><figcaption></figcaption></figure>

• Under Applications, click **Samanlik AI**.

<figure><img src="/files/d26O9tzw0QcrkCX0oX6x" alt=""><figcaption></figcaption></figure>

• Click the copy icon next to the URL to copy it.

<figure><img src="/files/hHSnj3VeZF9z0NFWDNFt" alt=""><figcaption></figcaption></figure>

### <mark style="color:red;">AI Powered Search — Installation & Integration (Next.js)</mark>

Part 2 showed you how to retrieve the application URL. With that URL in hand, you can now wire AI Powered Search into your storefront. If your project is built on Next.js, follow the steps in this part; for Django (Omnife/Akinon) projects, see Part 4 instead.

This part describes how to integrate the AI Powered Search package into Next.js projects for all brands. It is prepared to enable technical teams to perform a fast and standardized integration.

#### <mark style="color:red;">**1. Package Installation**</mark>

```
yarn add git+https://bitbucket.org/akinonteam/samanlik-client-js.git
```

#### <mark style="color:red;">2. Environment Variables</mark>

**Required**

```json
SAMANLIK_API_URL=https://<ai-powered-search-api-url>
```

**Optional**

The following variables are optional. Default values are used if not defined.

<table data-header-hidden><thead><tr><th valign="middle"></th><th valign="middle"></th></tr></thead><tbody><tr><td valign="middle"><strong>Variable</strong></td><td valign="middle"><strong>Default</strong></td></tr><tr><td valign="middle">SAMANLIK_FALLBACK_PATH</td><td valign="middle">/list/</td></tr><tr><td valign="middle">SAMANLIK_PREFIX_PATH</td><td valign="middle"><em>(empty)</em></td></tr><tr><td valign="middle">SAMANLIK_LANGUAGE</td><td valign="middle">tr</td></tr><tr><td valign="middle">SAMANLIK_TIMEOUT</td><td valign="middle">5000</td></tr></tbody></table>

#### <mark style="color:red;">3. Creating the Server Action</mark>

Create the file `src/views/header/samanlik-client.tsx`:

```typescript
'use server';
import { getNavigationAction } from 'samanlik-client';
import { ROUTES } from '@theme/routes';
 
const fetchSearchRedirectionResult = async (search_text: string) => {
  const params = new URLSearchParams();
  params.append('search_text', search_text);
 
  if (process.env.SAMANLIK_API_URL === undefined) {
    return { url_path: `${ROUTES.LIST}/?${params.toString()}` };
  }
 
  try {
    const result = await getNavigationAction(search_text);
    if (result.error || !result.url_path) {
      console.error('AI Powered Search API Error:', result.error);
      return { url_path: `${ROUTES.LIST}/?${params.toString()}` };
    }
    return { url_path: result.url_path };
  } catch (error) {
    console.error('AI Powered Search fetch error:', error);
    return { url_path: `${ROUTES.LIST}/?${params.toString()}` };
  }
};
 
export default fetchSearchRedirectionResult;
```

#### <mark style="color:red;">4. Search Component Integration</mark>

**Import**

```
import fetchSearchRedirectionResult from '../samanlik-client';
```

**Usage**

* The AI Powered Search API call must be added to the `handleSearchQuery` function.
* On a successful response, redirect using `router.push(data.url_path)`.
* On error, the user is redirected to the list page as a fallback.

#### <mark style="color:red;">5. File Structure</mark>

```
src/views/header/
├── samanlik-client.tsx
├── search/
│   └── index.tsx
└── index.tsx
```

#### <mark style="color:red;">6. Testing</mark>

* Start the project with `yarn dev`.
* Enter test queries into the search box (e.g. polo, tişört, ayakkabı).
* Verify that the redirect works correctly.
* Test the fallback redirect in case of an API error.

### <mark style="color:red;">Installation & Integration (Django)</mark>

The previous part covered the Next.js integration. If your storefront runs on Django (Omnife/Akinon) instead, this part walks through the equivalent setup — achieving the same search-redirection behavior through Django’s server-side configuration and context processor.

This part describes how to integrate the AI Powered Search package into Django (Omnife/Akinon) projects for all brands. It is prepared to enable technical teams to perform a fast and standardized integration.

#### <mark style="color:red;">1. Package Installation</mark>

```
yarn add git+https://bitbucket.org/akinonteam/samanlik-client-js.git
```

#### <mark style="color:red;">2. Environment Variables</mark>

**2.1. Required**

```
SAMANLIK_API_URL=https://<ai-powered-search-api-url>
```

{% hint style="info" %}
`SAMANLIK_API_URL` is the base URL of the AI Powered Search service. This URL is accessible from the Samanlik project deployed on ACC (Akinon Commerce Cloud). Contact your platform administrator to obtain the correct endpoint for your environment.
{% endhint %}

**2.2. Optional**

The following variables are optional. Default values are used if not defined.

<table data-header-hidden><thead><tr><th valign="middle"></th><th valign="middle"></th></tr></thead><tbody><tr><td valign="middle"><strong>Variable</strong></td><td valign="middle"><strong>Default</strong></td></tr><tr><td valign="middle">SAMANLIK_FALLBACK_PATH</td><td valign="middle">/list/</td></tr><tr><td valign="middle">SAMANLIK_PREFIX_PATH</td><td valign="middle"><em>(empty)</em></td></tr><tr><td valign="middle">SAMANLIK_LANGUAGE</td><td valign="middle"><em>(empty)</em></td></tr><tr><td valign="middle">SAMANLIK_TIMEOUT</td><td valign="middle">5000</td></tr></tbody></table>

{% hint style="info" %}
All configuration variables — including optional ones — are read from the server-side environment and passed to the frontend via Django’s context processor. JavaScript cannot access .env files directly in this setup
{% endhint %}

#### <mark style="color:red;">3. Django Settings</mark>

Two changes are required in the Django layer: reading all configuration variables from the environment and making them available to all templates through a context processor.

**3.1. omnife\_base/settings.py**

Add the following lines to expose all environment variables to Django and register the context processor that will pass them to templates.

```
SAMANLIK_API_URL       = env('SAMANLIK_API_URL',       cast=str, default='')
SAMANLIK_FALLBACK_PATH = env('SAMANLIK_FALLBACK_PATH', cast=str, default='/list/')
SAMANLIK_PREFIX_PATH   = env('SAMANLIK_PREFIX_PATH',   cast=str, default='')
SAMANLIK_LANGUAGE      = env('SAMANLIK_LANGUAGE',      cast=str, default='')
SAMANLIK_TIMEOUT       = env('SAMANLIK_TIMEOUT',       cast=int, default=5000)
 
CONTEXT_PROCESSOR_OPTIONS.append('omnife_base.context_processors.samanlik_context')
```

* All five variables are read at startup. Safe defaults are used so the application starts normally when variables are not set — in this case, the search falls back to the standard list page.
* Registering samanlik\_context ensures that all Samanlik configuration is injected into every template context automatically, without requiring manual passing in each view.

**3.2. omnife\_base/context\_processors.py**

Add the following function. It reads all Samanlik settings from Django and exposes them to templates.

```python
from django.conf import settings
 
def samanlik_context(request):
    return {
        'samanlik_api_url':       settings.SAMANLIK_API_URL,
        'samanlik_fallback_path': settings.SAMANLIK_FALLBACK_PATH,
        'samanlik_prefix_path':   settings.SAMANLIK_PREFIX_PATH,
        'samanlik_language':      settings.SAMANLIK_LANGUAGE,
        'samanlik_timeout':       settings.SAMANLIK_TIMEOUT,
    }
```

Using lowercase template keys follows the Django context processor convention and avoids conflicts with environment variable names in the template layer.

#### <mark style="color:red;">4. Template Integration</mark>

Expose all configuration values as global JavaScript variables in `templates/layout/base.html` so that frontend scripts can access them at runtime:

```html
<script>
  window.SAMANLIK_API_URL       = "{{ samanlik_api_url }}";
  window.SAMANLIK_FALLBACK_PATH = "{{ samanlik_fallback_path }}";
  window.SAMANLIK_PREFIX_PATH   = "{{ samanlik_prefix_path }}";
  window.SAMANLIK_LANGUAGE      = "{{ samanlik_language }}";
  window.SAMANLIK_TIMEOUT       = {{ samanlik_timeout }};
</script>
```

When `SAMANLIK_API_URL` is not configured, this renders as an empty string and the service file falls back gracefully to the list page. Note that `SAMANLIK_TIMEOUT` is rendered without quotes so `JavaScript` receives it as a number.

#### <mark style="color:red;">5. Creating the Service File</mark>

Create the file `templates/utils/samanlik-service.js.` This module wraps the `samanlik-client` package and exposes a single `async` function used by search components throughout the project.

All configuration is read exclusively from `window.*` globals injected by Django — no `process.env` access is needed or used.

```javascript
import { SamanlikClient, SamanlikError } from 'samanlik-client';
 
const SAMANLIK_API_URL       = (typeof window !== 'undefined' && window.SAMANLIK_API_URL)       || '';
const SAMANLIK_FALLBACK_PATH = (typeof window !== 'undefined' && window.SAMANLIK_FALLBACK_PATH) || '/list/';
const SAMANLIK_PREFIX_PATH   = (typeof window !== 'undefined' && window.SAMANLIK_PREFIX_PATH)   || '';
const SAMANLIK_LANGUAGE      = (typeof window !== 'undefined' && window.SAMANLIK_LANGUAGE)      || '';
const SAMANLIK_TIMEOUT       = (typeof window !== 'undefined' && window.SAMANLIK_TIMEOUT)       || 5000;
 
export const getSearchRedirectionUrl = async (searchText) => {
  const fallbackUrl = `${SAMANLIK_FALLBACK_PATH}?search_text=${encodeURIComponent(searchText)}`;
 
  if (!SAMANLIK_API_URL) {
    console.error('SamanlikClient: SAMANLIK_API_URL is not set.');
    return { error: 'Server configuration error', search_text: searchText, url_path: fallbackUrl };
  }
 
  try {
    const client = new SamanlikClient({
      apiUrl:       SAMANLIK_API_URL,
      language:     SAMANLIK_LANGUAGE || undefined,
      timeout:      SAMANLIK_TIMEOUT,
      prefixPath:   SAMANLIK_PREFIX_PATH || undefined,
      fallbackPath: SAMANLIK_FALLBACK_PATH,
    });
    const navigationUrl = await client.getNavigationUrl(searchText);
    return { error: null, search_text: searchText, url_path: navigationUrl };
  } catch (error) {
    console.error(`SamanlikClient Error: ${error.message}`, error);
    return { error: error.message, search_text: searchText, url_path: fallbackUrl };
  }
};
 
export default { getSearchRedirectionUrl };
```

The function always returns an object with a url\_path field — either the AI Powered Search result or the fallback URL — so callers do not need to handle exceptions.

#### <mark style="color:red;">6. Search Component Integration</mark>

**Import**

```
import { getSearchRedirectionUrl } from '@Utils/samanlik-service';
```

**Usage**

* The AI Powered Search API call must be added to the search input handler with a debounce (500ms recommended). This pre-fetches and caches the redirect URL while the user is still typing, so it is ready by the time the form is submitted.
* Cache the returned `url_path` in a component-level variable (cachedSamanlikUrl). If the API has already responded before the user submits, no second request is needed.
* If the API transforms the query text (e.g. normalises a Turkish character variant), update the search input field value accordingly before passing it to the autocomplete service.
* On form submit or **View All** button click, redirect using `window.location.href = urlPath`.
* On error, the user is redirected to the list page as a fallback.

```javascript
class Autocomplete {
  constructor(...) {
    this.cachedSamanlikUrl = null;
    // ...
    this.setupSamanlikRedirection();
  }

  setSearchActions() {
    const onSearchInput = debounce(async () => {
      const input = this.searchInput.value?.trim();
      if (!input) return;
 
      const result = await getSearchRedirectionUrl(input);
      this.cachedSamanlikUrl = result.url_path;
 
      // If the API transformed the query, update the input field
      const transformedText = this.extractSearchTextFromUrl(result.url_path);
      if (transformedText && transformedText !== input.toLowerCase()) {
        this.searchInput.value = transformedText;
      }
 
      // Proceed with autocomplete suggestions using the (possibly transformed) query
    }, 500);
 
    this.searchInput?.addEventListener('input', onSearchInput);
  }
 
  setupSamanlikRedirection() {
    this.searchForm.addEventListener('submit', async (e) => {
      e.preventDefault();
      const searchText = this.searchInput?.value?.trim();
      if (!searchText) return;
 
      // Use the cached URL if already fetched during typing; otherwise call the API now
      const urlPath = this.cachedSamanlikUrl
        || (await getSearchRedirectionUrl(searchText)).url_path;
 
      window.location.href = urlPath;
    });
  }
}
```

#### <mark style="color:red;">7. File Structure</mark>

```
omnife_base/
├── settings.py            ← All SAMANLIK_* variables + context processor registration
└── context_processors.py  ← samanlik_context()
 
templates/
├── layout/
│   └── base.html          ← window.SAMANLIK_* global variables
├── utils/
│   └── samanlik-service.js ← getSearchRedirectionUrl()
└── components/
    └── autocomplete/
        └── index.js       ← search component using samanlik-service
```

#### <mark style="color:red;">8. Testing</mark>

* Set `SAMANLIK_API_URL` in `.env` and start the project with `python` `manage.py` runserver.
* Open the browser console and verify that all `window.SAMANLIK_*` variables are populated with the correct values.
* Enter test queries into the search box (e.g. polo, tişört, ayakkabı) and verify that the redirect works correctly.
* Temporarily remove `SAMANLIK_API_URL` from `.env` and confirm the fallback redirect (/list/?search\_text=...) is used instead.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.akinon.com/technical-guides/ai-powered-search/installation-and-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.