Installation and Setup

Installation and setup

This page is the practical starting point for getting Adaptive Customer Engagement running locally or on a live WordPress install.

Requirements

• WordPress 6.0 or newer
• PHP 7.4 or newer
• Node.js 18 or newer if I am building from source
• npm 9 or newer

Installing from source

1. Put the plugin into wp-content/plugins/Adaptive-Customer-Engagement.

2. From the plugin directory, run:

   npm install
   npm run build

3. Activate Adaptive Customer Engagement in wp-admin.

Multisite and mapped subsite notes

The current build is now safer on multisite as well:

• the plugin uses its own admin-page slug family rather than a short shared slug
• plugin-owned asset, admin, and REST bootstrap URLs are normalised so they resolve against the current site host rather than assuming the primary domain
• the plugin bootstrap constants are plugin-specific, which matters when other active plugins use similar ACE-prefixed names

If I am testing this on a mapped subsite, I still want to clear any stale admin page cache after deployment so the browser is not hanging on to an older bundle URL.

What happens on activation

On activation, the plugin creates its schema and prepares its core settings so the tracking and admin surfaces are ready to use.

The main plugin bootstrap lives in adaptive-customer-engagement.php, and the schema is managed through the database layer under includes/Database/.

First setup pass in wp-admin

Once the plugin is active, I generally work through setup in this order:

1. Tracking
   Decide whether I want pageviews, downloads, click-to-call events, and native form submissions tracked.

2. Privacy
   Review retention windows, Do Not Track behaviour, internal-IP handling, and the default admin-user exclusion.

3. Phone numbers
   Add a default number first, then any source- or page-specific routing rules. This page now also shows the live numbers already claimed in Amazon Connect, and I can load one straight into a local routing-rule draft.

4. Enrichment
   Choose a provider only if I want company enrichment switched on.

5. Amazon Connect
   Save the identifiers and regional settings I want ready for the later integration phase. The setup screen now also has room for the S3 export bucket and prefix, the flow log group, a basic pre-flight readiness checklist, claimed-number tools, flow tools, and the current operational call-import status before I start deeper live Connect testing.

6. AI
   Connect the OpenAI key, check the token, choose the model I want to use, then set the chatbot name, opening message, placeholder text, source-display behaviour, live-site context rules, and frontend visibility rules for the company-and-products assistant.

AI setup notes

When I am turning the frontend assistant on, I normally work through this order:

1. enable AI features
2. add the OpenAI API key
3. run the token check so the model list loads
4. choose the model
5. set the chatbot name and opening message
6. decide whether the assistant should stay admin-only or go public
7. keep live site context enabled so product and company answers stay grounded

The assistant now also supports:

• live chat handover to admins
• operator suggestions and typing visibility
• passive lead capture for company and follow-up details
• postcode- and basket-aware delivery answers from the live WooCommerce shipping setup where the site shipping data is usable

The frontend assistant is now aimed at company, product, and service questions. It is not meant to present itself as a generic website-help widget.

Frontend number placeholders

I can place these in templates, blocks, or rendered content:

<span data-ace-phone="default">Loading…</span>
<a href="#" data-ace-phone-link="default">Call us</a>

The frontend script resolves the most appropriate number for the current page and source context, then replaces the text or tel: link.

Sample data

If I want to review the admin UI before I have real traffic, I can seed the local sample dataset from the dashboard. That fills the plugin with recent-looking sessions, companies, calls, top pages, WooCommerce interest, and tracking numbers.

Those demo tracking numbers stay visible in admin, but they are kept out of live frontend number resolution so they do not interfere with real routing.

Recommended live rollout

When I am rolling this out on a real site, I usually treat it like this:

1. activate the plugin
2. review privacy settings first
3. add a default phone number
4. check that the frontend number replacement behaves as expected
5. confirm events are reaching the dashboard
6. only then switch on any enrichment provider

Amazon Connect pre-flight

Before I start the first live Connect tests, I want this page to be filled in as far as possible:

• AWS region
• Amazon Connect instance ID
• S3 export bucket
• S3 export prefix
• flow log group
• credentials mode
• default contact flow ID where available

The admin page now includes a readiness checklist so I can see whether the plugin’s Phase 1 and Phase 2 foundations are in good enough shape before I begin the integration work itself.

I can also use the phone-number setup screen to search available Amazon Connect numbers and claim one without leaving WordPress, then finish its local routing rule straight away.

The Connect area also exposes the live import-status view and the manual call-import action, so I can check whether the export bucket and matching flow are behaving as expected without leaving wp-admin.