README

The official Clerk.io extension for Magento 1. It connects your store to Clerk.io's AI platform, giving you personalized search, product recommendations, and visitor tracking out of the box.

Version: 4.8.6 · PHP: 5.3+ · Magento: 1.9.x

What It Does

This extension handles three things:

1. Feeds your product data to Clerk.io — Exposes controller endpoints (/clerk/api/) that the Clerk.io platform calls to sync your catalog. Also pushes real-time updates when products are saved, deleted, or when catalog rules/stock changes.

2. Renders Clerk.io on the frontend — Injects Clerk.js on every page, which handles search results, live search dropdowns, recommendation sliders, exit-intent popups, and tracking.

3. Tracks visitor behavior — Logs page views, clicks, cart contents, completed orders, and refunds so Clerk.io's AI can learn and improve results.

Feature Overview

Installation

1. Download the latest release from GitHub.
2. Install via Magento Connect or extract into your Magento root directory preserving the folder structure.
3. Log out and back in to the admin panel (required for ACL refresh).
4. Configure at System > Configuration > Clerk > Settings.

Enter your API keys from my.clerk.io.

Full setup guide: help.clerk.io/integrations/magento-1/extension

How It Works Under the Hood

Data Feed Endpoints

All under the /clerk/api/ route. Auth logic is in ApiController.php.

There are also diagnostic and configuration management endpoints available for Clerk.io platform integration.

Magento Events Observed

Global scope:

Frontend scope:

Admin scope:

Frontend Router Overrides

The extension overrides two Magento frontend routers:

• catalogsearch — Clerk_Clerk_CatalogSearch is loaded before Mage_CatalogSearch, replacing the search results controller.
• checkout — Clerk_Clerk_Checkout is loaded after Mage_Checkout, extending the cart controller for powerstep.

Structure

├── code/
│   ├── controllers/
│   │   ├── ApiController.php              ← Data feed API (product, order, category, etc.)
│   │   ├── CatalogSearch/ResultController.php ← Overrides native search results
│   │   ├── Checkout/CartController.php    ← Extends cart for powerstep redirect
│   │   ├── BasketController.php           ← Cart contents endpoint
│   │   ├── ClerkLogger.php                ← Logging
│   │   └── Adminhtml/ClerkController.php  ← Admin dashboard controllers
│   │
│   ├── Model/
│   │   ├── Observer.php                   ← All event observers (product sync, basket, powerstep, refunds)
│   │   ├── Config.php                     ← Config path constants
│   │   ├── Communicator.php               ← Clerk.io API client
│   │   ├── Catalog/Product.php            ← Product model rewrite
│   │   ├── Catalog/Productbase.php        ← Product data builder
│   │   ├── Productpage.php                ← Product page data
│   │   └── Orderpage.php                  ← Order page data
│   │
│   ├── Block/
│   │   ├── Tracking.php                   ← Clerk.js init block
│   │   ├── Search.php                     ← Search results block
│   │   ├── SalesTracking.php              ← Order tracking block
│   │   ├── Powerstep.php                  ← Powerstep block
│   │   ├── ExitIntent.php                 ← Exit intent block
│   │   ├── Widget/Content.php             ← Recommendations widget
│   │   └── Adminhtml/Dashboard.php        ← Admin dashboard (my.clerk.io iframe)
│   │
│   ├── Helper/Data.php                    ← Data helper
│   │
│   └── etc/
│       ├── config.xml                     ← Module config (routes, observers, events, defaults)
│       ├── system.xml                     ← Admin configuration fields
│       ├── widget.xml                     ← Clerk Content widget definition
│       └── adminhtml.xml                  ← ACL & admin menu
│
├── design/
│   └── frontend/base/default/
│       ├── layout/clerk.xml               ← Frontend layout (block placement)
│       └── template/clerk/
│           ├── tracking.phtml             ← Clerk.js loader + config + basket tracking
│           ├── search.phtml               ← Search results page
│           ├── livesearch.phtml           ← Live search span
│           ├── facets.phtml               ← Faceted search container
│           ├── salestracking.phtml        ← Order tracking span
│           ├── powerpage.phtml            ← Powerstep page template
│           ├── powerpopup.phtml           ← Powerstep popup template
│           ├── exitintent.phtml           ← Exit intent span
│           └── widget/content.phtml       ← Recommendation widget
│
├── etc/modules/Clerk_Clerk.xml            ← Module declaration
│
└── devenv/                                ← Docker development environment
    └── restart.sh

Customizing & Extending

If you need to customize the extension, here are the parts to be careful with.

CatalogSearch/ResultController.php overrides native search. The extension registers its router before Mage_CatalogSearch, completely replacing the search results page. If another extension also overrides CatalogSearch, there will be a conflict.

Checkout/CartController.php extends the cart controller. Registered after Mage_Checkout to add the powerstep redirect after add-to-cart. Other extensions modifying the cart controller need to be aware of this.

Model/Catalog/Product.php is a model rewrite. The extension rewrites the product model via config.xml (<rewrite><product>Clerk_Clerk_Model_Catalog_Product</product></rewrite>). Only one module can rewrite a model — this will conflict with other extensions that rewrite the same class.

All observers are in one file. Model/Observer.php contains every event observer. If you need to modify observer behavior, this is the single file to look at.

Local code pool overrides. Copy any class from app/code/community/Clerk/Clerk/ to app/code/local/Clerk/Clerk/ to override it safely. Magento loads local before community.

Template overrides. Copy templates from app/design/frontend/base/default/template/clerk/ to your theme's template directory.

Layout overrides. Override clerk.xml in your theme's layout directory to move, remove, or add blocks.

Development Environment

A Docker environment is included for local development.

# Start Magento 1.9.2 with sample data + Clerk extension
./devenv/restart.sh -b http://$(docker ip)/

Shell access:

docker exec -i -t clerk-magento /bin/bash

Troubleshooting

• Extension not appearing: Check app/etc/modules/Clerk_Clerk.xml exists. Clear cache (rm -rf var/cache/*). Log out and back in to admin.
• Config not showing: Log out and back in (ACL refresh required after install).
• Search not working: Verify API keys in System > Configuration > Clerk.
• Products missing from feed: Visit /clerk/api/product?limit=1 (with auth) to check the feed. Check product visibility settings.
• Real-time sync not working: Check realtime_updates is enabled in config. Check var/log/clerk_log.log for errors.

Enable logging at System > Configuration > Clerk > Logging Settings — set to "File" to write to var/log/clerk_log.log.

Links

• Setup Guide
• Data Sync Docs
• Clerk.js Docs
• Design Template Language
• API Reference
• Dashboard

Contributing

1. Fork and branch from master
2. Use the included Docker environment for testing
3. Open a PR with a clear description

Issues & feature requests: github.com/clerkio/clerk-magento/issues

Support

• help.clerk.io · support@clerk.io · status.clerk.io