<div align="center">

# Manago AI for Magento 2

Elegant Magento 2 integration for Manago AI marketing automation, ecommerce tracking, contact synchronization, and storefront engagement tools.

[Documentation](https://support.manago.ai/integration-with-magento-1-2/)

</div>

## Description

This package connects your Magento 2 store with Manago AI and helps you turn customer activity into actionable marketing data. It supports contact synchronization, purchase and cart event tracking, monitoring code injection, and selected onsite engagement features directly from your Magento environment.

Designed for merchants and developers, the module keeps store data flowing into Manago AI so marketing, automation, and customer communication can stay aligned with real ecommerce behavior.

## Key Features

- Track key ecommerce events such as cart updates and purchases.
- Synchronize contacts, historical transactions, and consent status.
- Send customer profile data including email, phone, address, company, and date of birth.
- Add monitoring code to the storefront automatically.
- Assign tags for registrations, newsletter signups, purchases, and store-specific flows.
- Support contact form integration and transfer monitoring parameters with submitted data.
- Enable selected onsite features such as Live Chat, Pop-up Basic, and Web Push.
- Support back synchronization to verify whether registering customers already exist in the Manago AI database.

## Requirements

- PHP >= 7.4
- cURL extension
- Magento 2 installation

## Installation

For production:

```bash
composer require benhauer/manago-ai-integration --no-dev
```

For development:

```bash
composer require benhauer/manago-ai-integration
```

Then run the Magento setup commands:

```bash
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:flush
```

## What You Can Manage

- Contact data and subscription preferences
- Cart and purchase activity
- Monitoring and tracking setup
- Store-related tags and segmentation data
- Engagement features available through Manago AI

## Newsletter Status Callbacks

Manago AI uses signed callbacks to synchronize newsletter status changes back to Magento. The module generates store-scoped callback URLs based on the Magento base URL and store-code configuration:

- `salesmanago/newsletter/in` changes an existing subscriber to subscribed.
- `salesmanago/newsletter/out` changes an existing subscriber to unsubscribed and sends the standard Magento unsubscription email.

Each request must contain an `email` and a valid signed `key`. The module validates the callback against the current store configuration and can fall back to the default scope when appropriate. Invalid requests do not change subscriber data.

Since version 4.18.1, callback processing works as follows:

- Status updates are idempotent. If the subscriber already has the requested status, Magento returns a successful response without writing to `newsletter_subscriber` again.
- Callback-initiated saves are marked as programmatic, preventing the newsletter plugin and observer from sending the same status change back to Manago AI.
- Newsletter synchronization triggered by Magento runs after the database transaction commits, reducing lock contention on `newsletter_subscriber`.
- Callback responses are JSON only. The endpoints do not redirect to or render the storefront.
- Successful and controlled no-change responses use HTTP `200` and include `success` and `message` fields.
- Persistence or runtime failures use HTTP `503` with `Retry-After: 60`, allowing the caller to retry after a delay.
- Operational error logs contain a hash of the email, store scope, request duration, and exception type instead of the full subscriber email.

These callbacks are required for status synchronization from Manago AI to Magento. Blocking or disabling them stops opt-in and opt-out changes made in Manago AI from being reflected in Magento.

## Newsletter Double Opt-In Processing

When Double Opt-In is enabled, a new Magento newsletter subscription is first synchronized to Manago AI and the local subscriber status is then changed from `Subscribed` to `Unconfirmed`. The module marks this internal status change as programmatic, so it is not synchronized back to Manago AI and cannot recursively start another subscriber save.

The internal save is idempotent. A subscriber that already has the `Unconfirmed` status is not saved again. After a successful registration, Magento keeps one subscriber record associated with the customer, and the subscriber remains `Unconfirmed` until the opt-in callback confirms the subscription.

Newsletter handling depends on the configuration of the subscriber's store view:

| Configuration | Behavior |
| --- | --- |
| Double Opt-In = `No` | The module does not perform the internal `Unconfirmed` status change. Newsletter changes use the configured synchronization strategy. |
| Double Opt-In = `Yes`, Disable event handling via plugin method = `No` | The newsletter resource-model plugin starts synchronization. The internal `Unconfirmed` save is marked as programmatic and skipped by the plugin. |
| Double Opt-In = `Yes`, Disable event handling via plugin method = `Yes` | The resource-model plugin does not synchronize the change. The commit observer handles it and ignores the programmatic `Unconfirmed` save. |
| Processing mode = `sync` | Synchronization runs during the current request. The programmatic marker prevents the internal Double Opt-In save from re-entering synchronization. |
| Processing mode = `async` | Eligible updates are queued. If async requirements are not met, the existing fallback to synchronous processing is used. The internal status save does not create another queue message through plugin re-entry. |
| Synchronize contacts statuses = `Yes` or `No` | This setting independently controls whether registration reads the contact consent status from Manago AI. It does not select plugin or observer handling. |

`Double Opt-In`, `Processing mode`, and `Disable event handling via plugin method` are store-view settings. Before selecting the plugin or observer path, the module loads configuration using the subscriber's `store_id`. This allows different store views to use different newsletter settings without reusing configuration previously loaded for another store.

Programmatic saves made by the Manago AI opt-in and opt-out callbacks use the same protection. They update Magento without sending the callback-initiated status change back to Manago AI.

## Learn More

See the full integration guide at:

https://support.manago.ai/integration-with-magento-1-2/
