Amino Engine

Description

Amino Engine for WooCommerce is the official connector for Amino Engine, an email marketing
automation service for online stores.

It sends your store’s events to Amino Engine so that automated emails — abandoned cart, welcome,
order confirmation, back in stock, price drop, win-back — fire on real facts about real orders.

Connecting takes no clicks at all if you downloaded this plugin from your own Amino Engine
account: activate it and it connects itself, because the download you asked for already carries a
one-time code for your account. There is no key to copy and nothing to paste.

A copy installed from WordPress.org has no such code, so after you activate it a notice appears
at the top of your dashboard with a single Connect to Amino Engine button. Press it and the
plugin is connected. Nothing at all leaves your site until you press that button. (You can still
paste a key by hand on the settings page if you prefer.)

What makes this connector different

• Nothing is sent and forgotten. Every event goes into a queue in your own database, is
  delivered with a real HTTP request whose status code is actually read, and is retried on a
  1 minute / 5 minute / 30 minute / 2 hour / 12 hour schedule. Anything that still fails lands in a
  dead-letter list you can see and re-drive from the settings page. There is no configuration in
  which an event disappears without you being able to see that it did.
• Purchases are never inferred from a page load. Order events come from the order record
  changing state, not from the shopper reaching the thank-you page. If a shopper closes the tab,
  pays through a redirecting gateway, or the receipt page is cached, the purchase is still recorded.
• The opt-in checkbox is an artifact, not a guess. The exact sentence the shopper saw is stored
  with their consent. A box that was never on screen — an Apple Pay or Google Pay express checkout,
  for example — records nothing at all, rather than being treated as a refusal.
• Works on both checkouts. The classic (shortcode) checkout and the Blocks checkout are both
  supported, using the Additional Checkout Fields API on Blocks. The Diagnostics tab tells you which
  one your store is actually running.
• Abandoned-cart links that rebuild the cart. The recovery link is a short, expiring, opaque
  token pointing at a snapshot held on your own server. It contains no personal data, it cannot be
  edited to add a product, and it merges into an existing cart rather than wiping it.
• High-Performance Order Storage (HPOS) compatible, declared and implemented — the plugin uses
  the WooCommerce CRUD API exclusively and never touches order post meta.
• A password-free door for wholesale customers. Put [aminoengine_code_gate purpose="wholesale_portal"
redirect="/wholesale/"] on a page and your wholesale buyers get in by typing their email address and
  the six-digit code Amino Engine emails them. There is no password for them to forget, nothing for you
  to reset, and the code is never stored on your site — your site only ever asks Amino Engine whether
  the code somebody typed was the right one.
• Safe on staging. The plugin binds your key to the site URL it was activated on. A staging
  clone carrying a copy of your live database will queue and log events but send nothing, and it
  says so in a banner. This stops a staging refresh from firing duplicate emails at real customers.

External services

This plugin is an interface to Amino Engine, an email marketing automation service operated by
Amino Engine (https://aminoengine.com). The plugin is not useful without an Amino Engine account.

If you installed this plugin from WordPress.org, nothing at all is transmitted until you press
Connect, or paste an API key and it validates. Installing or activating the plugin sends nothing.

If you downloaded this plugin from your own Amino Engine account, it connects itself. That copy
contains a file called connect.json holding a one-time connection code that was created for your
account while you were signed in to Amino Engine and pressed the button to download it — the screen
you pressed it on says, in one sentence, that the plugin will connect itself. So on the first
WordPress admin page you open after activating it, the plugin sends that code and connects. You are
then shown “Connected to Amino Engine” and there is nothing to press. It does this once, never
over a plain-http site, and never when the plugin already holds a working key. If it is refused for
any reason you are shown why, and a Connect button to try again.

If that copy finds a key already stored on this site, it first asks Amino Engine whether that key
still exists (a GET https://app.aminoengine.com/api/v1/ping presenting the stored key, the same
request the “Validate and save” button makes). If the key still works, nothing further happens and
the connection code is not used. If Amino Engine answers that it does not recognise the key, the
plugin forgets it and connects with the code from your download. If Amino Engine cannot be reached,
the key is left exactly as it is. This check only ever happens on a copy downloaded from your own
Amino Engine account. A copy installed from WordPress.org never makes it.

The one request it makes goes to https://app.aminoengine.com
(/api/connect/wordpress/plugin/hello) and carries only: the one-time connection code that came
with your download, your site address, the plugin, WordPress and WooCommerce version numbers, and
your site’s public appearance — your site title, your logo URL, the colour palette and font names
your theme declares, and the addresses of any Google Fonts stylesheets your storefront loads. That
last part is so your emails come out in your own colours and type without you setting them up by
hand; every one of those values is already visible in the source of every page of your shop. Amino
Engine answers with the API key for your account and the plugin stores it.

If you installed this plugin from WordPress.org rather than downloading it from your Amino Engine
account, the Connect button instead opens https://app.aminoengine.com in your browser so you can
approve the connection while signed in; Amino Engine then delivers the key back to this site’s own
REST endpoint (/wp-json/amino-engine/v1/connect), which accepts it only for the request you just
started. No data about your store or your customers is sent in either case.

If you connected your store from inside Amino Engine using WordPress’s own “Authorize
Application” screen, Amino Engine already holds an administrator application password for this
site. It may then install and switch this plugin on for you, and hand it the key straight away
through this site’s own REST endpoint (/wp-json/amino-engine/v1/adopt). That request has to be
signed in as an administrator of this site to be accepted, and it is refused outright if this store
is already connected and working. You can stop it at any time by revoking the “Amino Engine”
application password at Users -> Profile.

Connecting also creates a WordPress application password named “Amino Engine” for the
administrator who pressed it, and sends it in that same request so Amino Engine can read your
orders, customers and products. It is created with WordPress’s own Application Passwords feature —
the same thing the approval screen at Users → Profile creates — and you can see and revoke it there
at any time. Revoking it stops Amino Engine reading your store and nothing else. If your site does
not have application passwords available, this step is skipped and the plugin connects without one.

Once connected, the plugin sends the following to https://app.aminoengine.com:

• Store events — order id, order number, order status, order date, line items (product id,
  variant id, SKU, name, quantity, price), order totals, coupon codes, payment and shipping method,
  billing and shipping address, customer note; cart contents and totals; checkout state; product
  catalog records including price and stock. Sent when the corresponding thing happens in your store.
• Customer identity — the billing email address on an order, or the account email of a logged-in
  customer, plus an anonymous random browser identifier. Sent alongside the events above.
• Consent records — the email address, the exact wording of the opt-in checkbox that was shown,
  whether it was ticked, the shopper’s IP address and browser user agent, and the time. Sent when a
  shopper submits a form that contained the checkbox.
• Diagnostic information — your site URL, plugin version and WooCommerce version, as request
  headers, so support can identify the installation.

The plugin also loads a small JavaScript file (ae.js) from the tracking hostname shown on the
settings page, on your storefront pages. It records page views, product views and cart activity
against the anonymous browser identifier described above. It is a first-party, service-related
script and is not loaded until you connect a key.

Why that one script tag is printed directly rather than enqueued. Everything else this plugin
puts on a page — all of its CSS, and the small checkout listener — goes through wp_enqueue_style(),
wp_enqueue_script() and wp_add_inline_script(). The tracking tag is the single exception, and
there are three reasons it has to be:

1. It carries its own data-key and data-host attributes, which is how it knows which store it is
   for. wp_enqueue_script() produces a plain src tag; attributes need a script_loader_tag
   filter, and a filter can be unhooked, reordered or stripped by another plugin without anything
   saying so.
2. It must load async and as early in <head> as possible, because everything it measures happens
   after it. Enqueueing resolves dependency ORDER, not absolute position.
3. It has to print on themes that never call wp_head(). Some do, and on those the enqueue system
   never runs at all — which is exactly how one shop’s homepage went untracked for weeks. The plugin
   watches the page being built and inserts the tag before </head> itself when that happens.

The tag is a fixed string with no user input in it, and nothing per-visitor is ever written into it,
so a cached copy of a page is safe to serve to anybody.

• Service: https://aminoengine.com
• Terms of service: https://app.aminoengine.com/legal/terms
• Acceptable use policy: https://app.aminoengine.com/legal/acceptable-use
• Sub-processors: https://app.aminoengine.com/legal/sub-processors
• Privacy policy: https://aminoengine.com/privacy

Deleting the plugin removes all of its own data from your WordPress database. It does not
delete anything on the Amino Engine side — that is a separate, deliberate action in the Amino
Engine console.

Wholesale and portal gates

Some of your customers need to get into something that is not for everybody — a wholesale price list, a
reseller portal, a document library, a page of bulk order forms.

This plugin can put a door in front of any page, with no password and no extra account:

1. The customer types the email address you have for them.
2. Amino Engine emails them a six-digit code that expires in ten minutes.
3. They type the code and they are in, for twelve hours, on that browser.

Setting it up takes one line. Put this shortcode on the page you want people to arrive at first:

[aminoengine_code_gate purpose="wholesale_portal" redirect="/wholesale/"]

(If a page of yours still has the old [ae_code_gate] on it from version 1.0.8 or 1.0.9, edit that
page and change the tag to [aminoengine_code_gate]. Keep the same settings inside the brackets.)

purpose is your own name for this door — use a different one for each door, and a code for one will

never open another. redirect is where somebody lands once they are through; it must be a page on your
own site.

Then protect the page itself. In your theme’s template, or in a block that runs PHP:

if ( ! aminoengine_gate_passed( 'wholesale_portal' ) ) {
    wp_safe_redirect( home_url( '/wholesale-login/' ) );
    exit;
}

aminoengine_gate_email( 'wholesale_portal' ) hands you the address they proved, so you can show their own

prices.

Building your own screens instead. Two PHP functions and two REST endpoints do the same job:

$sent = aminoengine_send_code( 'buyer@example.com', 'wholesale_portal' );
$ok   = aminoengine_verify_code( 'buyer@example.com', 'wholesale_portal', '481920' );

POST /wp-json/amino-engine/v1/code/send     {"to":"…","purpose":"…"}
POST /wp-json/amino-engine/v1/code/verify   {"to":"…","purpose":"…","code":"481920"}

Both answer {"ok":true} or {"ok":false,"reason":"…","error":"a sentence you can show somebody"}.

What this is, and what it is not. Passing the gate proves that whoever is holding that browser can
read email sent to that address. That is the right strength for a price list. It is not a WordPress
login and it grants no permissions, so do not use it in place of a customer account for anything a
WordPress role already protects — order history, downloads, or anything that can be changed.

The safety rules, so you do not have to think about them.

• Codes are six digits and expire in ten minutes.
• Asking for a new code cancels the old one.
• Five wrong codes locks that address for fifteen minutes.
• Your site never stores the code — not in the database, not in a log, not anywhere.
• The “you are signed in” cookie is signed, cannot be read by JavaScript, cannot be edited to say
  somebody else’s address, and cannot be used on a different door.
• A staging copy of your site will not send codes, for the same reason it does not send anything else.