# Connect your Magento 2 store

> Install the Releva module for Magento 2, paste your Secret Key per store view, switch on web push and the consent cookie, and check in Releva that data arrives.

The Releva module for Magento 2 (`Releva_Releva`) puts the Releva tracking snippet on every storefront page, serves the catalog and subscriber endpoints Releva pulls from, and sends cart changes and order status changes from your Magento server. You install it once per Magento installation and activate it once per **store view** with that store view’s **Secret Key** from Releva.

The module itself is not configured inside Releva. In Releva you create one shop per store view with platform **Magento 2.x**, copy its **Secret Key**, and later check that events, products and profiles arrive. Those checks are the recorded steps on this page.

> **Note**
>
> The steps inside the Magento admin and their screenshots are from 2022-2023 and can look different in your version.

## Before you start

* A shop in Releva with **Platform** set to **Magento 2.x**. The platform is chosen on **Create Shop** and cannot be changed later. If your shop was created as **Other / Custom**, ask your account manager to create a Magento shop; a custom shop does not get the Magento default URLs. See [How accounts, shops and billing work](https://releva.ai/documentation/learn/account/how-accounts-shops-and-billing-work/).
* One Releva shop **per store view** you want to track. Each store view gets its own **Secret Key**. Mixing store views under one key mixes their data in Releva.
* The module archive from your Releva account manager.
* Shell access to the Magento root to run `bin/magento` commands, and a Magento admin user who may change **Stores › Configuration**.
* Your shop must reach `https://releva.ai` over TLS from the server, and trust its certificate chain. The module calls the Releva API when you save the key; an untrusted CA makes the save fail with `Releva API Error: Curl error: 60`.

## Install

1. Extract the module archive into `<magento_root>/app/code/Releva/Releva`.

2. From the Magento root, run:

   ```plaintext
   bin/magento module:enable Releva_Releva
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento setup:static-content:deploy -f
   bin/magento cache:flush
   ```

   If your installation puts `magento` on the path, you can leave out the `bin/` prefix.

3. In the Magento admin, open **Stores › Configuration**. A **Releva** section with **Integration Settings** appears in the left column.

   ![Magento admin: the Stores menu with Configuration highlighted](https://releva.ai/documentation/_astro/magento2-store-configuration-releva-menu.DauQqu2R_2dNGyb.webp) *Merchant platform (Magento 2 admin).*

   If the section is missing, flush the cache again. You may need to restart the web server (or the Magento container) before **Releva** shows up under **Stores › Configuration**.

## Configure

### In Releva: copy the Secret Key

1. Open **Settings › Shop & Integration**. On the **General** tab, **Platform** shows **Magento 2.x**. If your account has several shops, pick the shop for this store view in the shop switcher first.
2. Scroll to **Secret Key** and select the copy icon next to it. The module asks only for this key; the **Access Token** is not typed into Magento.

The screenshots of these two steps are in [Verify](https://releva.ai/documentation/integrations/magento/magento-2/#verify). For the two keys and what each is for, read [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/).

### In Magento: activate the store view

1. In **Stores › Configuration › Releva › Integration Settings**, open the **Scope** switcher at the top left and select the **store view** you are connecting, for example **Default Store View**. Do not stay on **Default Config** when you have several store views.

   ![Magento admin: scope switcher open with Default Store View highlighted](https://releva.ai/documentation/_astro/magento2-store-view-scope-switcher.CsEKExpA_ZRShc6.webp) *Merchant platform (Magento 2 admin).*

2. Clear **Use Website** next to **Secret Key** and paste the key you copied from Releva. The field’s help text still says “Settings -> Shop”; the current path in Releva is **Settings › Shop & Integration › General**.

3. Select **Save Config**. From now on the module inserts the Releva tracking snippet and the personalization blocks on the storefront pages. Flush the Magento cache if nothing changes.

   ![Magento admin: Integration Settings with the Secret Key field and Save Config highlighted](https://releva.ai/documentation/_astro/magento2-integration-settings-secret-key.eBzgfhEA_1OiGjD.webp) *Merchant platform (Magento 2 admin). The key value is masked.*

4. Repeat for every other store view, each with the **Secret Key** of its own Releva shop.

### Optional: collect web push permissions

Skip this if you do not send web push notifications from Releva.

1. From the Magento root, run `bin/magento releva:serviceworker:install` and flush the cache. Then open `https://your-shop.example.com/releva-service-worker.min.js` in a browser; the file must load.

2. In **Integration Settings**, set **Collect push notification permissions?** to **Yes** and select **Save Config**. Flush the cache.

   ![Magento admin: Collect push notification permissions set to Yes](https://releva.ai/documentation/_astro/magento2-push-notification-permissions.DlIswe0N_2v4vTI.webp) *Merchant platform (Magento 2 admin). The key value is masked.*

If the install command fails, run it as a user who may write to the Magento root, or copy `releva-service-worker.min.js` from the module into the web root yourself. Once visitors accept the browser prompt, the Releva SDK registers the worker and posts the subscription to Releva. Sending is covered in [How push notifications work](https://releva.ai/documentation/learn/push-notifications/how-push-notifications-work/).

### Required under GDPR and similar laws: the consent cookie

Under **Privacy and Data Protection**, enter the name of the cookie your consent banner sets when a visitor agrees to analytics and first-level marketing, in **Consent cookie name**. If the cookie must also hold a specific value, enter it in **Consent cookie value**; leave the value empty to check only that the cookie exists. Example: a banner that sets `cookielaw=1` needs name `cookielaw` and value `1`.

![Magento admin: Privacy and Data Protection with Consent cookie name and value](https://releva.ai/documentation/_astro/magento2-privacy-consent-cookie.D5TCFjPk_Z1KPsu1.webp) *Merchant platform (Magento 2 admin). The key value is masked.*

You are responsible for configuring this correctly where data protection law applies to you.

### In Releva: check the sync settings

When the shop was created with platform **Magento 2.x**, Releva filled in three addresses from the shop **URL**:

| Setting                                          | Where in Releva                                                                              | Default                                                                            |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Catalog sync URL (**Catalog Sync Type** **API**) | **Settings › Shop & Integration › Catalog Sync**                                             | `https://your-shop.example.com/releva/integration/products`                        |
| **Subscriber Sync API**                          | **Settings › Messaging › General**, visible when **Subscription Management** is **External** | `https://your-shop.example.com/releva/integration/subscribers`                     |
| **Email Unsubscribe URL**                        | Same place                                                                                   | `https://your-shop.example.com/newsletter/manage/` (Magento’s own newsletter page) |

Two things are not set for you:

* **Catalog Sync Schedule** is empty. Releva presets a nightly schedule for Shopify shops only. Without a cron expression Releva never pulls your full catalog on its own; **Sync Now** starts one by hand. To add a schedule, follow [Schedule a full catalog sync](https://releva.ai/documentation/guides/shop-settings/schedule-a-catalog-sync/).
* **Subscription Management** defaults to **Internal** on **Create Shop**. In that mode the two subscriber fields are hidden. If Magento stays the record of who is subscribed to your newsletter, switch to **External** and save: [Choose how Releva manages subscriptions](https://releva.ai/documentation/guides/consent/choose-how-releva-manages-subscriptions/).

If your store view’s base URL differs from the shop **URL** in Releva (store code in the path, a subfolder, `index.php`), edit the addresses accordingly.

## Verify

### Check that Releva sees your Magento shop

Recorded in the Releva admin on a demo shop set to **Magento 2.x**, as a regular shop user. Nothing is typed or saved. The shop name, URL and keys are masked, and the catalog address uses an example host.

1. Open **Settings › Shop & Integration**. On the **General** tab, **Platform** shows **Magento 2.x** or **Magento 1.x**.

   ![Step 1](https://releva.ai/documentation/_astro/step-1.CexV93Td_18WVga.webp)

2. **Secret Key** is the key the Releva extension asks for in your Magento admin. Select the copy icon next to it to copy it.

   ![Step 2](https://releva.ai/documentation/_astro/step-2.B-RhAptt_MPMY2.webp)

3. Select the **Catalog Sync** tab.

   ![Step 3](https://releva.ai/documentation/_astro/step-3.DZsGWjUw_Z2sarHD.webp)

4. With **API** selected, the address ends in `/releva/integration/products`. This is the catalog endpoint of the extension, filled in when your shop was created in Releva.

   ![Step 4](https://releva.ai/documentation/_astro/step-4.BPEdV56p_ZU9MxR.webp)

5. **Catalog Sync Schedule** stays empty until you enter a cron expression. Without one, Releva runs no scheduled full sync; **Sync Now** starts one by hand.

   ![Step 5](https://releva.ai/documentation/_astro/step-5.CD7_U7r-_27WquT.webp)

6. **Sync History** lists each catalog sync with its status and product count. **Last successful sync** shows when Releva last read your catalog; **Never** means it has not read it yet.

   ![Step 6](https://releva.ai/documentation/_astro/step-6.BfrJ5FsB_Z1mdGtQ.webp)

Select **Test** next to the address to make Releva request page 1 of your catalog endpoint with your secret key; the response, or the error, appears under the field. Select **Sync Now** to start a full sync; it appears in **Sync History** once it has run.

### Check that your shop’s data reaches Releva

Open your storefront in a browser, view a page or two and a product, then check **Data Platform › Events**, **Data Platform › Products** and **Data Platform › Profiles**. The screens are the same for every integration: [Check that your store data arrives](https://releva.ai/documentation/integrations/check-that-your-store-data-arrives/).

Other event types to look for once the module runs: **Viewed Product**, **Cart Item Added**, **Cart Checkout Completed** and **Registered**. Without **Include Anonymous Profiles**, the profiles list contains only profiles with an email address or phone number.

## Troubleshooting

**The Releva section is missing under Stores › Configuration.** Run `bin/magento setup:upgrade` and `bin/magento cache:flush` again; you may also need to restart the web server process. Make sure the module sits in `app/code/Releva/Releva`, not one level deeper.

**Nothing appears in Data Platform › Events.** Check that you saved the key in the **store view** scope you are browsing, not only in **Default Config**, and that you flushed the cache. Open the storefront page source and look for `releva-sdk-js`. If your consent cookie is configured, accept the banner first. Use the [tracking-snippet check](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#check-the-tracking-snippet-with-curl) to confirm the shop’s **Access Token** works.

**Test next to the catalog URL fails.** Releva calls `GET {url}?page=1` with `authorization` and `x-rlv-authorization: Bearer <secretKey>` and expects JSON with `products` and `pageCount` or `nextCursor`. A `404` means the module is not active for that store view or the URL does not match your base URL (store code, subfolder). An authentication error means the key in Magento differs from the one in Releva; both must be the **Secret Key** of the same shop. The contract is in [the catalog pull-sync reference](https://releva.ai/documentation/reference/catalog/let-releva-pull-your-catalog/).

**Products disappear from Releva after a full sync.** About 120 seconds after a complete pass, Releva deletes every product the endpoint did not return. Products disabled or out of stock should still be returned with `available: false`. See [Full syncs delete what they do not see](https://releva.ai/documentation/learn/catalog/how-your-catalog-gets-into-releva/#full-syncs-delete-what-they-do-not-see).

**Sync History stays at Last successful sync: Never.** No schedule is preset for Magento shops. Enter a cron expression under **Catalog Sync Schedule** or select **Sync Now**.

**Add-to-cart answers 400 from the Releva API.** `POST /api/v0/carts/update` rejects unknown top-level keys and the paid-order fields `cartPaid` and `orderId`. Prices sent as PHP decimal strings such as `"12.5000"` are accepted.

**The same customer triggers “Registered” conversions on every page.** This no longer happens. The module renders `registeredAt` in `window.relevaProfile` on every page for a logged-in customer; Releva fires **Registered** and the ad-platform registration events only when it first records the registration. Nothing to configure.

**Help links in the Releva admin open old documentation URLs.** The **Catalog Sync** tab links to `/documentation/sync-apis/periodical-product-sync/`; its content is now in [the catalog pull-sync reference](https://releva.ai/documentation/reference/catalog/let-releva-pull-your-catalog/).

## What syncs

What a module sends can change between module versions. If you depend on one of these calls, ask your account manager whether your module version makes it.

| Data                                                        | Direction and endpoint                                                                                                                                                                                                                                                                               | When                                                                               |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Page views, product views, searches, the logged-in customer | Browser. The module renders the Releva SDK snippet; the SDK posts the page context to `POST /api/v0/push/{accessToken}`. The customer is in `window.relevaProfile`, with `registeredAt` on every page                                                                                                | Every storefront page                                                              |
| Registration                                                | Same push. Releva records **Registered** once, on the push that first records the registration                                                                                                                                                                                                       | First page after sign-up                                                           |
| Cart changes                                                | Server. The module’s add-to-cart observers send the full current cart to `POST /api/v0/carts/update` with the secret key, identified by the SDK cookies `rlv_u` / `rlv_p` or by email/phone. Releva derives **Cart Created**, **Cart Item Added**, **Cart Item Removed** and **Cart Updated** events | On add-to-cart and cart changes                                                    |
| Catalog, full                                               | Releva pulls `GET https://your-shop/releva/integration/products?page=&cursor=` with `authorization` and `x-rlv-authorization: Bearer <secretKey>`; the module serves this route                                                                                                                      | **Catalog Sync Schedule**, **Sync Now**, or `POST /api/v0/products/sync`           |
| Product deletes                                             | `DELETE /api/v0/products/{id}` by plain product id                                                                                                                                                                                                                                                   | On product delete                                                                  |
| Catalog, incremental                                        | `POST /api/v0/products`, `POST /api/v0/products/availability`                                                                                                                                                                                                                                        | On product save or stock change                                                    |
| Subscribers, full                                           | Releva pulls `GET https://your-shop/releva/integration/subscribers?page=&cursor=` (same headers); each item is upserted as a profile with its `subscribedAt`                                                                                                                                         | **Sync Now** next to **Subscriber Sync API**, or `POST /api/v0/subscribers/sync`   |
| Orders                                                      | `POST /api/v0/carts` with `cartPaid` and `orderId`                                                                                                                                                                                                                                                   | On order placement                                                                 |
| Order status                                                | `POST /api/v0/events` with `action: orderStatusChanged`; a storefront `statusLabel` may accompany an internal status code                                                                                                                                                                            | On order status change                                                             |
| Newsletter consent                                          | `POST /api/v0/subscribe` / `POST /api/v0/unsubscribe`; the **Email Unsubscribe URL** default points at Magento’s `newsletter/manage/` page                                                                                                                                                           | On newsletter changes                                                              |
| Web push subscriptions                                      | The SDK registers `releva-service-worker.min.js` and posts the subscription to `POST /api/v0/pushSubscriptions/{accessToken}`                                                                                                                                                                        | When **Collect push notification permissions?** is **Yes** and the visitor accepts |
| Tracking consent                                            | The module checks the configured consent cookie before tracking                                                                                                                                                                                                                                      | Every page                                                                         |
| Product blocks and banners                                  | Rendered by the SDK from the push response; the module places them on “all relevant pages”                                                                                                                                                                                                           | Every page                                                                         |
| Refunds                                                     | `POST /api/v0/refunds`                                                                                                                                                                                                                                                                               |                                                                                    |

## Next steps

* [Check that your store data arrives](https://releva.ai/documentation/integrations/check-that-your-store-data-arrives/): Confirm that events, products and customers from your shop reach Releva.
* [Choose how Releva manages subscriptions](https://releva.ai/documentation/guides/consent/choose-how-releva-manages-subscriptions/): Decide whether Releva or your shop manages subscriptions, and whether sign-ups need a confirmation.
* [Schedule a full catalog sync](https://releva.ai/documentation/guides/shop-settings/schedule-a-catalog-sync/): Set where Releva pulls your catalog from and how often.
* [How Releva connects to your shop](https://releva.ai/documentation/learn/shop-settings/how-releva-connects-to-your-shop/): Learn what your two keys, the tracking snippet and the catalog pull sync do.