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.

AI Powered Search — Installation Guide

Overview

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.

Prerequisites

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

Quick Start

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

Installation Steps

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 guide.
• In the Application Name field, type Samanlik AI and press Search.

• Click Samanlik AI in the results list.

Step 2 — Select Your Project

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

• Click Configure Application Values.

Step 3 — Configure Required Fields

Fill in the following required fields:

Field	Description
COMMERCE_APP_URL	The URL of your Commerce application
OMNITRON_CHANNEL_ID	The channel ID of your Sales Channel in Omnitron

OMNITRON_USERNAME and OMNITRON_PASSWORD are optional feature fields. You do not need to fill them in for a standard installation.

How to Find COMMERCE_APP_URL

• Go to the Commerce Cloud Projects page.

• Select your project.

• Click the Commerce application.

• Copy the application URL displayed on the page.

• Paste it into the COMMERCE_APP_URL field.

How to Find OMNITRON_CHANNEL_ID

For detailed information on configuring Sales Channels, see the Omnitron Sales Channel guide.

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

• 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.

Step 5 — Install

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

• Click Install.

Verification

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:

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.

API Health Check

Send the following request to confirm the API is responding:

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.

Accessing the AI Powered Search Application URL

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.

Overview

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

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.

Prerequisites

• 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.

Steps

• Log in to Commerce Cloud.
• Navigate to Projects.

• Select the project where AI Powered Search is installed.

• Under Applications, click Samanlik AI.

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

AI Powered Search — Installation & Integration (Next.js)

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.

1. Package Installation

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

2. Environment Variables

Required

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

Optional

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

Variable	Default
SAMANLIK_FALLBACK_PATH	/list/
SAMANLIK_PREFIX_PATH	(empty)
SAMANLIK_LANGUAGE	tr
SAMANLIK_TIMEOUT	5000

3. Creating the Server Action

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

'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;

4. Search Component Integration

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.

5. File Structure

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

6. Testing

• 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.

Installation & Integration (Django)

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.

1. Package Installation

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

2. Environment Variables

2.1. Required

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

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.

2.2. Optional

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

Variable	Default
SAMANLIK_FALLBACK_PATH	/list/
SAMANLIK_PREFIX_PATH	(empty)
SAMANLIK_LANGUAGE	(empty)
SAMANLIK_TIMEOUT	5000

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

3. Django Settings

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.

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.

4. Template Integration

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

<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.

5. Creating the Service File

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.

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.

6. Search Component Integration

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.

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;
    });
  }
}

7. File Structure

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

8. Testing

• 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.