Integration Guide

Deploy Sovereign Core
in minutes.

Two deployment models. Choose the one that fits your infrastructure. Choose your integration method below — GTM requires only a tag container, no code. The API method connects directly to your stack for full control. Both methods work across all Sovereign Core packages: Starter, Growth, Commerce, and Enterprise.

GTM Method · No Code Required · Available on Starter and above

What you need: An active Google Tag Manager container on your website. That's it. No server access, no code deployment required.

Request access & domain registration

Contact us with your domain. We add your domain to Sovereign Core's allowed origins so signals can reach our server. This is a one-time step that takes under 5 minutes on our end.

Why this step? Sovereign Core uses CORS (Cross-Origin Resource Sharing) to ensure only authorized domains can send signals. Your domain must be whitelisted before integration.

Request Access →

Set up Consent Mode Default in GTM

Before your GTM container fires any tags, consent must be set to denied by default. Create a new Custom HTML tag with Consent Initialization trigger.

/* GTM Tag: Consent Mode Default */
/* Trigger: Consent Initialization - All Pages */

<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){ dataLayer.push(arguments); }

  gtag('consent', 'default', {
    'analytics_storage': 'denied',
    'ad_storage': 'denied',
    'ad_user_data': 'denied',
    'ad_personalization': 'denied',
    'wait_for_update': 500
  });
</script>

Add the Sovereign Lite signal tag

Create a new Custom HTML tag in GTM. Set the trigger to All Pages. This tag sends behavioral signals to Sovereign Core on every page load.

/* GTM Tag: Sovereign Lite — Signal */
/* Trigger: All Pages */

<script>
function sendSovereignSignal(consent) {
  fetch("https://sovereign.smyrnaandsable.com/gtm/signal", {
    method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({
      consent: consent,
      page: window.location.pathname,
      event: "pageview",
      scroll_depth: 0,
      time_on_page: 0,
      exit_point: document.referrer || "direct"
    })
  }).catch(function(e) {});
}

// Check consent status and send signal
var consentStatus = document.cookie.indexOf('consent_status=granted') !== -1;
sendSovereignSignal(consentStatus);
</script>

Add consent update tags

Create two more tags to handle when users accept or decline cookies. These update Google's consent state and route signals correctly.

When user accepts

/* GTM Tag: Consent Mode — Accept */
/* Trigger: Custom Event → consent_granted */

<script>
  gtag('consent', 'update', {
    'analytics_storage': 'granted',
    'ad_storage': 'granted',
    'ad_user_data': 'granted',
    'ad_personalization': 'granted'
  });
</script>

When user declines

/* GTM Tag: Consent Mode — Decline */
/* Trigger: Custom Event → consent_decline */

<script>
  gtag('consent', 'update', {
    'analytics_storage': 'denied',
    'ad_storage': 'denied',
    'ad_user_data': 'denied',
    'ad_personalization': 'denied'
  });
</script>

Publish and verify

Publish your GTM container. Open GTM's Tag Assistant and visit your site. You should see the Sovereign Lite Signal tag firing. Within minutes, traffic will appear in the Sovereign Core demo dashboard.

✅ Integration complete. Sovereign Core will now analyze inbound traffic, model anonymous behavioral cohorts from non-consenting users, and begin building your Privacy-Preserving Audience Intelligence (PPAI) profile.

View Live Demo →

API Method · For Enterprise & IT Teams · Available on Growth and above

What you need: Server-side access to make HTTP requests. Sovereign Pro connects directly to your infrastructure — no GTM required.

Request your API key

Contact us to receive your Bearer API key. Keys are scoped, time-limited, and tied to your organization. Each key includes a name, tier, and expiry date.

Key format: A 64-character hex string. Used as a Bearer token in the Authorization header of every API request.

Request API Key →

Test your key

Verify your API key is active before making analysis requests.

Endpoint

GET /api/v1/test?key=YOUR_API_KEY

Expected response

{
  "status": "valid",
  "client": "YourOrganization",
  "tier": "pro",
  "expires_at": "2026-08-01T00:00:00"
}

Analyze inbound requests

Send traffic signals to Sovereign Core for real-time bot detection and behavioral analysis. Call this endpoint from your server — not from the browser — to keep your API key secure.

Endpoint

POST /api/v1/analyze

Request headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request body

{
  "user_agent": "Mozilla/5.0 (visitor's user agent)",
  "page": "/products/item-1",
  "headers": {
    "accept": "text/html,application/xhtml+xml",
    "accept-language": "nl-BE,nl;q=0.9"
  }
}

Response

{
  "sovereign_pro": "v1",
  "analysis": {
    "is_bot": false,
    "classification": "human",
    "risk_score": 8,
    "risk_signals": [],
    "action": "allow"
  },
  "gdpr": {
    "data_stays_in_eu": true,
    "no_pii_processed": true,
    "zero_knowledge": true
  },
  "timestamp": "2026-06-11T09:00:00"
}

Act on the response

Use the action field to decide what to do with each request.

# Python example
response = requests.post(
    "https://sovereign.smyrnaandsable.com/api/v1/analyze",
    headers={"Authorization": "Bearer YOUR_KEY"},
    json={
        "user_agent": request.headers.get("User-Agent"),
        "page": request.path,
        "headers": dict(request.headers)
    }
)

result = response.json()

if result["analysis"]["action"] == "block":
    # Bot detected — block or redirect
    return Response("Access denied", status=403)
else:
    # Human — proceed normally
    return serve_page()

✅ Integration complete. Your infrastructure now has server-side bot protection with GDPR-compliant behavioral intelligence. All data stays within EU infrastructure.

Commerce Module · Stock, Margin, Price & Seasonal Intelligence · Available on Commerce package

What you need: A product feed — stock levels, margin data, and pricing. This can be connected via a simple JSON feed, a CSV upload, or a direct API integration with your inventory system.

Provide your product data

Commerce Intelligence needs to know your stock levels, margins, and prices to generate recommendations. In the demo environment, this runs on mock data. For live use, you provide a structured feed.

/* Minimum product data structure */

{
  "id": "PROD-001",
  "name": "Product Name",
  "stock": 12,
  "capacity": 50,
  "margin_pct": 45,
  "price": 18.50,
  "season": ["all"]
}

Data sources we support: Manual JSON/CSV upload, scheduled feed via webhook, or direct API connection to common inventory platforms. No scraping, no unauthorised data collection — ever.

Stock Oracle generates recommendations

Based on stock-to-capacity ratio, Stock Oracle classifies each product and recommends a campaign action: stop, slow down, continue, or accelerate.

/* Thresholds */
Out of stock (0%)     → REMOVE_FROM_CAMPAIGNS
Critical (< 10%)      → STOP_CAMPAIGNS
Low (< 30%)            → SLOW_DOWN
Normal (30-70%)        → CONTINUE
High (> 70%)            → ACCELERATE

Margin Guard and Price Intelligence layer on top

Margin Guard combines margin data with stock levels to flag products where ad spend may not be profitable. Price Intelligence compares your pricing against publicly available competitor prices — never scraped, only from sources you provide or licensed data feeds.

Ethics note: Price Intelligence never accesses competitor systems directly. Data comes from your own market research, manual entry, or licensed pricing APIs (e.g. PriceAPI, Prisync).

Review via Commerce Intelligence dashboard

All four modules — Stock Oracle, Margin Guard, Price Intelligence, Seasonal Oracle — are visible in one dashboard. Each recommendation includes the reasoning behind it.

GET /admin/stock

✅ Commerce Intelligence active. Stock, margin, price, and seasonal signals now feed into your weekly Sovereign Core report — and into SCIE's strategic recommendations.

Ads Intelligence Layer · Phase 9 · Available on Growth and above

What this is: Ads Intelligence reads your PPAI behavioural cohort data and Commerce Intelligence signals, and translates them into plain-language advertising recommendations. By default, nothing is sent anywhere — your team acts manually on the insights. An optional Aggregate Signal mode exists for organisations that want to feed anonymous pattern data into their own ad platform's GDPR-compliant modelling tools.

Important: Non-consenting visitor data collected by Sovereign Core is never sent to Google, Meta, or any third party — regardless of mode. This is a hard boundary that does not change.

Insight Only mode (default — no setup required)

Ads Intelligence is active by default once your weekly report is generated. Visit the admin panel to see plain-language recommendations based on your PPAI cohorts and Commerce Intelligence signals. No additional configuration needed.

GET /admin/ads-intelligence

✅ Ready to use. Generate a weekly report first, then visit the Ads Intelligence admin page to see recommendations.

Aggregate Signal mode (optional — requires Google Ads API setup)

If your organisation wants to feed anonymous, non-identifying pattern signals into Google's own GDPR-compliant modelling tools (e.g. Consent Mode v2 modelled conversions), this requires connecting Sovereign Core to your Google Ads account via the Google Ads API.

Technical requirements for Google Ads API integration:

1. A Google Ads Manager Account (MCC) — standard advertiser accounts do not have API access. Create one at ads.google.com/home/tools/manager-accounts and link your existing account under it.

2. A Developer Token — applied for via Tools & Settings → API Center inside your Manager Account. Test Account level is approved immediately. Production level requires Google review (typically 1-2 weeks).

3. OAuth 2.0 credentials — a Client ID and Client Secret from Google Cloud Console (APIs & Services → Credentials → OAuth Client ID). Desktop app type is recommended for initial setup.

4. A Refresh Token — generated once through the OAuth flow using your credentials. Permanent thereafter.

This integration is performed by your technical team using your own Google Ads account credentials. Sovereign Core does not store or transmit your ad account credentials — you provide them at configuration time, scoped to your own infrastructure.

What data is shared — and what never is

In Aggregate Signal mode, only anonymous, statistical patterns are shared — never individual visitor data, never raw PPAI signals, never personal identifiers.

/* What MAY flow to your ad platform (opt-in, aggregate only) */
{
  "signal_type": "aggregate_cohort_pattern",
  "explorer_pct": 38,         // % of non-consenting visitors showing high engagement
  "bouncer_pct": 45,          // % showing low engagement
  "period": "weekly",
  "no_individual_data": true,
  "gdpr_compliant": true
}

/* What NEVER leaves Sovereign Core */
- Raw behavioral signals
- Individual visitor patterns
- Session hashes
- Any data that could identify a person

How Sovereign Core connects to your accounts · Read-only by default

Core principle: Sovereign Core never holds its own login to your Google Ads, GA4, or any other platform. It connects through credentials your organisation creates and controls, scoped to exactly the access you grant — and it is read-only everywhere except where you explicitly opt in to write access.

Google Analytics (GA4) — read-only, always

Your organisation creates a Service Account in your own Google Cloud project, then grants that Service Account "Viewer" or "Analyst" access to your GA4 property. Sovereign Core uses this to read traffic, conversion, and audience data — it cannot change GA4 settings, delete goals, or modify anything. This is a one-way data flow: GA4 → Sovereign Core.

What this means practically: Connecting GA4 carries effectively zero operational risk. There is nothing for Sovereign Core to break, because it never writes to GA4.

Google Ads — your account, your control, your final decision

Your organisation's own technical team creates the Developer Token, OAuth credentials, and Manager Account access — all within your own Google Ads account. These credentials are entered into Sovereign Core's environment configuration; we never have separate login access to your account.

Two distinct modes, and what each can do:

Insight Only (default): Sovereign Core reads nothing automatically and writes nothing. It generates recommendations in plain language — your team reviews them and makes changes manually, on your own timeline, through your own normal campaign management process.

Aggregate Signal (opt-in): Even when enabled, this shares only anonymous pattern data into Google's own modelling tools — it does not pause campaigns, does not change budgets, and does not take any direct action inside your Ads account without your team's involvement.

Sovereign Core does not pause campaigns or move budget on its own — ever, in any mode. Every recommendation is advisory. Your team decides what to act on and when, fitting it into your existing approval processes, budget cycles, and team schedules.

Data promise: Sovereign Core does not collect personal data. It never has anything personal to send anywhere — inside or outside Europe. Where aggregate signals are passed to Google Ads for machine learning optimisation, they contain no individual identifiers, because none were ever collected.

Onboarding starts in observation mode

When Sovereign Core is first connected to a new organisation, it begins by reading and reporting only — no recommendations are treated as urgent, no language implies an action must happen "today." This gives your team time to see how the system behaves before relying on its output for decisions.

Nothing is broken by connecting Sovereign Core. It adds a reporting and recommendation layer on top of your existing tools — it does not replace, reconfigure, or interrupt anything you already have running.

Deploy Sovereign Core
in minutes.

Ready to integrate?

Choose your level of independence

Deploy Sovereign Corein minutes.

Ready to integrate?

Choose your level of independence

Deploy Sovereign Core
in minutes.