Magento#

This module provide a link between a Magento webshop (front and backend) and the Antavo Enterprise Loyalty Cloud. The API-based integration strongly features Antavo’s JavaScript SDK and this combination kickstarts the integration of Antavo services whilst adapting the module to software and process requirements. This module executes functions within Magento and sends in various customer lifecycle events and transactional data to Antavo.

Compatibility#

The Antavo Magento module is compatible up to Magento 2.4.2 Magento 1.x series is not supported.

Note

Antavo strives to ensure that the integration module is compatible with as many third-party modules as possible. However, compatibility cannot be guaranteed with all modules from the Magento store and therefore it is strongly suggested that regression tests are performed before pushing the solution to production.

Prerequisites#

The following are required before integration:

Magento Open Source / Commerce 2.4.2
custom domain
a live, staging and test server
access to Antavo Enterprise Loyalty Cloud

The Antavo Magento module has the following dependencies

PHP 7.* (up to 7.4)
antavo/library-loyalty-apps from the package

Installation guide#

There are two install pathways:

Manual installation
1. Obtain the installation file from the Antavo Project team
2. Download and unzip the extension into a temporary directory
3. Copying unzipped extension to app folder
4. Run the Magento 2.x install command from root:
```
php bin/magento setup:upgrade
php bin/magento setup:di:compile
```
Magento Marketplace

The installation will soon be possible via the Magento Marketplace.

Configuration#

Antavo configurations are located at the following location withing Magento.

Stores ‣ Configuration ‣ Loyalty Apps ‣ General

This configuration section explains and expand each configurable option within the Antavo module.

Core

Authentication method:

Host-based authentication method (social/cookie)

Customer opt-in sending:

New user registrations will be sent to Antavo’s system, if enabled.

Redirect url:

The Full url which the customer is redirected to following enrollment from the microsite. An Empty value will result in a redirection back to the referrer page e.g., “https://www.google.com”

JS SDK hash method:

The preferred hashing method in the JS SDK. Accepted values: Hash/Query string
API.

All information required in this section is available in the API page of the Antavo Backoffice

Antavo ‣ Settings ‣ API

Region:

SDK configuration. Accepted values: dev/test/rc/demo/salesdemo/st1/st2

API URL:

The API URL, e.g., https://api.st1.antavo.com

SDK URL:

The SDK URL,specified in the API setting in the Antavo Backoffice e.g., https://api.st1.antavo.com/sdk/latest-apps

Client Id:

The API key e.g., 2546875357658765

Client secret:

The API secret e.g., 749184fbfa63c0edef9876a69939aa981f8e181a

Logging level:

See System ‣ Extensions ‣ Antavo Api Log . Options: none/errors only/All request
Purchase

Auto-generate coupon:

Enabling this feature results in the total number of spendable points (on the storefront) being automatically converted into a coupon. The normal behavior is for customers manually enter the amount of points to convert into a coupon.

Coupon settings box:

A field is enabled where customers can set the number of points to convert into a coupon. The total number of spendable points will be converted into a coupon automatically if this option is disabled.

Point exchange rate:

The exchange rate between points and coupon value.

Convert currency into base currency:

A ‘yes’ setting results in the local store currency being converted into the base currency

Reserve spent points (recommended):

Disabling this setting enables customers to spend their points before their orders are shipped and invoiced.

Checkout sending:

If this feature is enabled, new purchases will be sent to Antavo. The purchase in Magento still needs to be invoiced and shipped.
Discounts

Point limit:

Maximum number of points customers can use in a single checkout. A value is zero results in no upper limit.

Checkout sending type:

There are two options: Payment received - Send when purchase flow is completed. Purchase completed - Send when purchase’s invoiced and shipped.

Checkout discount code prefix:

Manual setting of the default checkout discount code prefix (ANTPB). Leave this field empty for the default value.

Point mechanism:

Generate discount coupon or use Magento reward module
Social share

Enabled:

Enable or disable the social share module on the Antavo Enterprise Loyalty Cloud.
Reviews

Enabled:

Enable or disable the gamified reviews module on the Antavo Enterprise Loyalty Cloud.

Affected business functions#

Purchase
- Tracking purchases
- Using points on the cart page
Discounts
- Generating coupons - friend referral, point burning
- Adding a new endpoint to generate coupons
User Management (Customer Lifecycle)
- Registration
- Opt-in
- Opt-out
- Login - authentication: 2 types (social network, cookie-based SSO)
- Update customer data upon a change
Review

Level of effort#

This highly versatile module needs tailoring to your order lifecycle as checkout updates, rejects, and accepts are not automatically covered by default. This highly customer specific module configuration has to be tailored to match your business requirements and to make this process as painless as possible, the module structure has been made compliant with the most strict Magento standards. This fine and stringent configuration means that intensive and extensive testing is necessary post-integration and webshop configuration.

Development work is required to integrate this extension but a system administrator is not required to carry out the integration. The collection of any loyalty-related data, either directly from the shop frontend or via the customer account area, requires the manual embedding of the Loyalty Hub, the responsive, loyalty focused landing page. This integration will not create a new CMS page nor add menu item to Magento.

The integration work usually takes between 8-48 man hours including the installation, plugin configuration and webshop preparation. You should have an intermediate knowledge of PHP and be quite familiar with Magento 2.x and its structure. You don’t have to be a certificated Magento expert to integrate this extension into your webshop system.

Help texts will guide you through the configuration of the module on its settings page.

Supported features#

The module handles registrations with loyalty opt-in, synchronizing changes to Antavo upon profile update and customer authentication. It also handles transactions by calling in checkouts, adding the ability to burn loyalty points, reserve-release points, creating and redeeming coupons. The module also enables the showcasing the number of points rewarded after purchasing a certain product, on the product page. The Antavo Loyalty module contains:

Core settings
- Environment config to separate stages e.g., test, staging, live
- Sync actual settings for the requested Antavo Loyalty brand
- Two methods for Authenticating users
  - cookie
  - social
- Optional opt-in event sending (store setting)
  - If activated, this results in new user registrations being sent to Antavo’s system
- Define redirect URL after enrollment (store setting)
- Configurable Antavo JS SDK hashing method
  - This sets the customer tracking identifier, appended in the webshop URL, as a query string parameter or a hash
API settings (tracking Antavo API communications)
- Define logging levels
  - all
  - errors
  - none
Purchase
- Auto-generate coupon (store setting)
  - This feature automatically converts the total number of spendable points (on the storefront) into a coupon rather than customers have to enter the number of points to convert into a coupon.
- Coupon settings box on cart page (store setting)
  - A field can be enable where customers can set the number of points to convert into a coupon. If this is disabled the total number of spendable points will be automatically converted into a coupon.
- Point exchange rate (store setting)
  - Sets the exchange rate between points and coupon value.
- Currency conversion (store setting)
  - The local currency can be transformed to base currency
- Reserve points, reserve - release (store setting)
  - Customers will be able to spend points before orders are shipped and invoiced.
- Checkout event sending for Antavo (store setting)
  - Enabling this feature results in new purchases being sent to Antavo’s system. This should be disabled if you wish to track online purchases through an OMS/ERP or from another third-party system.
Discount
- Single checkout point limit for customers (store setting)
- Two types of checkout events submittable to Antavo (store setting)
  - Payment received – Sent when the purchase flow has been completed
  - Purchase completed – Sent when purchase has been invoiced and shipped.
- Checkout discount coupon code prefix (price rule)
  - Default checkout discount code prefix (ANTPB) can be manually set.
- Friend referral coupon code prefix (main price rule and coupons)
  - Default friend referral discount code prefix (ANTFR) can be manually set.
- Friend referral coupon
  - website restriction
  - custom group restriction
  - segment restriction
- Point mechanism:
  - coupons
  - rewards (Magento 2 Enterprise Edition only)
  Note
  
  Antavo point burning can be set in two ways:
  Discount coupon generation
  
  The Magento reward module
Social share
- Enable social share module (store setting)
Reviews
- Enable gamified review module (store setting)

Checking configuration#

Open Magento’s MySQL database and navigate to table core_config_data. All the settings for the Loyalty Apps configuration can be accessed.

Enter Antavo.SDK.getBrand() in network’s console panel at your webshop will return the connected brand data upon a successful connection.

Antavo.SDK.getCustomer() will also returns the currently authenticated loyalty member (while auth type is cookie).

The customer getter will return null for the case when the auth type is social. In-browser cookies have to be checked in order to look at currently logged on customers.

The Antavo Loyalty Engine uses cookies for many of its functions. The Loyalty Hub thus needs to be running on the same top domain as your webstore in order for the engine to able read and write cookies.

Setting up a custom subdomain for your program, like http://loyalty.yourfirm.com/ is usually done in conjunction your DNS provider, typically the place where the domain for your website was registered.

The first step is is to set up a CNAME record which points to microsites.antavo.com.

This is done by configuring the DNS as follows:

yourfirm.com 1800 CNAME microsites.antavo.com

This can usually be done in the administration panel of your DNS provider. If this is not available, then connect the provider directly with above settings.

These settings need some time (up to 24 hours) to propagate across the internet . The result can be verified by opening the desired address in your web browser. A correct configuration should result in the Antavo’s default 404 page.

Testing#

A test environment is necessary to check the module before testing with live data. It is important to perform a load-test and check everything in an environment which closely resembles the production stages.

The testing phase (both environment test & staging) should include testing an additional third-party modules you would like to use to investigate their behavior with the Antavo extension.

Admin navigation:

Stores

Stores > Configuration

Stores > Configuration > LoyaltyApps

Stores > Configuration > LoyaltyApps > General