> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mention-me.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Encrypted Parameters

> How to encrypt personal data in Mention Me tag parameters and referral links using libsodium

export const SignInNotice = ({message = "To see code snippets pre-filled with your partner code"}) => {
  return <div data-mm-sign-in style={{
    display: "none"
  }}>
      <Info>
        {message}, <a data-mm-sign-in-link href="https://app.mention-me.com/sign-in"><strong>sign in</strong></a>.
      </Info>
    </div>;
};

export const MerchantContext = () => {
  const PARTNER_STORAGE_KEY = "mm-docs-partner";
  const escapeHtml = str => str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
  const getStoredPartner = () => {
    try {
      const raw = localStorage.getItem(PARTNER_STORAGE_KEY);
      if (!raw) return null;
      const data = JSON.parse(raw);
      if (data && data.partnerCode) return data;
    } catch (e) {}
    return null;
  };
  const setStoredPartner = data => {
    try {
      localStorage.setItem(PARTNER_STORAGE_KEY, JSON.stringify(data));
    } catch (e) {}
  };
  const clearStoredPartner = () => {
    try {
      localStorage.removeItem(PARTNER_STORAGE_KEY);
    } catch (e) {}
  };
  const captureQueryParams = () => {
    const params = new URLSearchParams(window.location.search);
    const partner = params.get("partner");
    const name = params.get("name");
    if (partner) {
      const data = {
        partnerCode: partner
      };
      if (name) data.displayName = name;
      setStoredPartner(data);
      params.delete("partner");
      params.delete("name");
      const qs = params.toString();
      const clean = window.location.pathname + (qs ? "?" + qs : "") + window.location.hash;
      window.history.replaceState(null, "", clean);
      return data;
    }
    return getStoredPartner();
  };
  const isLocal = typeof window !== "undefined" && window.location.hostname === "localhost";
  const API_BASE = isLocal ? "http://localhost:3001" : "https://app.mention-me.com";
  const SIGN_IN_BASE = isLocal ? "http://localhost:3001/sign-in" : "https://app.mention-me.com/sign-in";
  const MERCHANT_WINDOW_KEY = "__mmMerchantContext";
  const publishMerchant = data => {
    window[MERCHANT_WINDOW_KEY] = data;
    window.dispatchEvent(new CustomEvent("mm-merchant-ready", {
      detail: data
    }));
  };
  const clearMerchant = () => {
    delete window[MERCHANT_WINDOW_KEY];
  };
  const BADGE_ID = "mm-partner-badge";
  const showPartnerBadge = (partnerData, source) => {
    if (document.getElementById(BADGE_ID)) return;
    const nav = document.getElementById("navigation-items");
    if (!nav || !nav.parentNode) return;
    const badge = document.createElement("div");
    badge.id = BADGE_ID;
    badge.className = "mm-partner-badge";
    const hasName = partnerData.displayName && partnerData.displayName !== partnerData.partnerCode;
    const heading = hasName ? escapeHtml(partnerData.displayName) : escapeHtml(partnerData.partnerCode);
    const code = hasName ? escapeHtml(partnerData.partnerCode) : "";
    const codeStr = code ? ' <span class="mm-partner-badge-code">' + code + '</span>' : '';
    const resetTitle = source === "clerk" ? "Sign out and switch account" : "Clear personalisation";
    badge.innerHTML = '<div class="mm-partner-badge-inner">' + '<span class="mm-partner-badge-content">' + '<span class="mm-partner-badge-context">Personalised for </span>' + '<span class="mm-partner-badge-name">' + heading + '</span>' + codeStr + '</span>' + '<button class="mm-partner-badge-reset" title="' + resetTitle + '">&times;</button>' + '</div>';
    nav.parentNode.insertBefore(badge, nav);
    badge.querySelector(".mm-partner-badge-reset").addEventListener("click", e => {
      e.preventDefault();
      e.stopPropagation();
      if (source === "clerk" && window.Clerk && window.Clerk.signOut) {
        clearMerchant();
        const redirect = SIGN_IN_BASE + "?redirect_url=" + encodeURIComponent(window.location.href);
        window.Clerk.signOut().then(() => {
          window.location.href = redirect;
        }).catch(() => {
          window.location.reload();
        });
        return;
      }
      clearStoredPartner();
      window.location.reload();
    });
  };
  const removePartnerBadge = () => {
    const el = document.getElementById(BADGE_ID);
    if (el) el.remove();
  };
  const showNotices = () => {
    document.querySelectorAll("[data-mm-sign-in]").forEach(el => {
      el.style.display = "";
    });
    const redirect = SIGN_IN_BASE + "?redirect_url=" + encodeURIComponent(window.location.href);
    document.querySelectorAll("[data-mm-sign-in-link]").forEach(a => {
      a.href = redirect;
    });
  };
  const hideNotices = () => {
    document.querySelectorAll("[data-mm-sign-in]").forEach(el => {
      el.style.display = "none";
    });
  };
  const walkCodeBlocks = replacements => {
    document.querySelectorAll("pre code").forEach(codeEl => {
      let html = codeEl.innerHTML;
      if (replacements) {
        for (const [from, to] of replacements) {
          html = html.split(from).join(escapeHtml(to));
        }
      }
      const paramStyle = "color:inherit;filter:brightness(110%);font-weight:bold;text-decoration:underline;cursor:pointer";
      html = html.replace(/(\?|&amp;)([a-z_]+)=/g, (match, prefix, name) => {
        const slug = name.replace(/_/g, "-");
        const target = document.getElementById("param-" + slug);
        if (!target) return match;
        return prefix + '<a href="#param-' + slug + '" style="' + paramStyle + '">' + name + "</a>=";
      });
      codeEl.innerHTML = html;
    });
  };
  const observeTabSwitches = callback => {
    let processing = false;
    const observer = new MutationObserver(() => {
      if (processing) return;
      processing = true;
      setTimeout(() => {
        callback();
        processing = false;
      }, 50);
    });
    setTimeout(() => {
      const tabs = document.querySelector("[role='tablist']");
      if (tabs && tabs.parentElement) {
        observer.observe(tabs.parentElement, {
          attributes: true,
          subtree: true,
          childList: true
        });
      }
    }, 500);
  };
  const pollForClerk = (onReady, onTimeout) => {
    let n = 0;
    const tick = () => {
      if (window.Clerk && window.Clerk.loaded) {
        return onReady(window.Clerk);
      }
      if (++n < 40) {
        setTimeout(tick, 250);
      } else {
        onTimeout();
      }
    };
    setTimeout(tick, 100);
  };
  const fetchMerchantFromAPI = () => {
    return fetch(API_BASE + "/api/docs/context", {
      credentials: "include",
      cache: "no-store"
    }).then(res => res.ok ? res.json() : null);
  };
  useEffect(() => {
    let cancelled = false;
    const urlPartner = captureQueryParams();
    const onPersonalised = (merchant, source) => {
      if (cancelled) return;
      const replacements = [["YOUR_PARTNER_CODE", merchant.partnerCode]];
      if (merchant.displayName) {
        replacements.push(["YOUR_TRADING_NAME", merchant.displayName]);
      }
      hideNotices();
      showPartnerBadge(merchant, source);
      walkCodeBlocks(replacements);
      observeTabSwitches(() => walkCodeBlocks(replacements));
    };
    const onUnauth = () => {
      if (cancelled) return;
      clearMerchant();
      removePartnerBadge();
      showNotices();
      walkCodeBlocks(null);
      observeTabSwitches(() => walkCodeBlocks(null));
    };
    const tryUrlFallback = () => {
      if (cancelled) return;
      if (urlPartner) {
        onPersonalised(urlPartner, "url");
      } else {
        onUnauth();
      }
    };
    if (!document.cookie.includes("__client_uat")) {
      tryUrlFallback();
      return;
    }
    pollForClerk(clerk => {
      if (cancelled) return;
      if (!clerk.session) {
        tryUrlFallback();
        return;
      }
      fetchMerchantFromAPI().then(data => {
        if (data) {
          publishMerchant(data);
          onPersonalised(data, "clerk");
        } else {
          tryUrlFallback();
        }
      }).catch(() => tryUrlFallback());
    }, () => {
      if (!cancelled) tryUrlFallback();
    });
    return () => {
      cancelled = true;
    };
  }, []);
  return null;
};

<MerchantContext />

<Note>
  All traffic between Mention Me and your site is encrypted via HTTPS by default. Further encryption is only needed in specific cases — discuss your use case with your Client Success Manager before implementing.
</Note>

## Overview

If you pass personal data in a landing page URL or tag, you can encrypt it so intermediaries cannot read it. Mention Me uses the [Sodium crypto library](https://doc.libsodium.org/) (libsodium) with XSalsa20 encryption.

A shared secret key (64-character hex string) is exchanged between you and Mention Me. You use it to encrypt; we use it to decrypt.

Without encryption, a referral link looks like:

```
https://mention-me.com/me/referral/register/er/YOUR_PARTNER_CODE?email=test@example.com&firstname=John&surname=Smith
```

With encryption:

```
https://mention-me.com/me/referral/register/er/YOUR_PARTNER_CODE?mm_e=923173becee4ec7b...9abe&nonce=11baf0cb9972615536256b13
```

Contact your onboarding manager to receive your encryption key.

## Step-by-Step

<SignInNotice />

<Steps>
  <Step title="URL-encode your parameters">
    Each parameter value must be URL-encoded first. For example, `person@example.com` becomes `person%40example.com`.
  </Step>

  <Step title="Build the query string">
    Concatenate all parameters with `&`:

    ```
    email=person%40example.com&firstname=John&surname=Smith
    ```
  </Step>

  <Step title="Generate a nonce">
    Create a random 24-byte (48-character) hex-encoded nonce. This **must** be different each time.

    Example: `11baf0cb9972615536256b13b2981c1d3cc86508718af061`
  </Step>

  <Step title="Encrypt with libsodium">
    Encrypt the query string using `crypto_secretbox` from the Sodium library with your shared key and the nonce. This produces a binary cipher text.

    Libraries are available for:

    * [JavaScript](https://github.com/jedisct1/libsodium.js)
    * [Python](https://github.com/stef/pysodium)
    * [PHP](https://paragonie.com/book/pecl-libsodium/read/00-intro.md#installing-libsodium)
    * [Other languages](https://doc.libsodium.org/bindings_for_other_languages)
  </Step>

  <Step title="Hex-encode the output">
    Convert the binary encrypted output to a hex string.
  </Step>

  <Step title="Pass as mm_e parameter">
    Add the encrypted data and nonce to your tag or URL:

    ```
    mm_e=<hex_encoded_ciphertext>&nonce=<hex_encoded_nonce>
    ```
  </Step>
</Steps>

## Validation

Encryption **must** include a valid email address as one of the encrypted fields, otherwise the request will be rejected.

## Example

Given:

* **Query string**: `email=person%40example.com&firstname=John&surname=Smith`
* **Key**: `1234567890123456789012345678901234567890123456789012345678901234`
* **Nonce**: `123456789012345678901234567890123456789012345678`

The encrypted output would be:

```
mm_e=923173becee4ec7bdcfb6820d1e77026adb54f66c6e00abbee470967b114f8653b3e17e906749214406ff8c1105f48f79a9634d11576c3284c2fbfaa4a281fbdd9b6e05dfb9abe&nonce=123456789012345678901234567890123456789012345678
```

### In a referrer tag

Unencrypted:

```html theme={null}
<script type="text/javascript"
  src="https://tag.mention-me.com/api/v2/referreroffer/YOUR_PARTNER_CODE?email=person@example.com&firstname=John&surname=Smith&order_number=253829&order_total=113&order_currency=GBP&situation=postpurchase">
</script>
```

Encrypted equivalent:

```html theme={null}
<script type="text/javascript"
  src="https://tag.mention-me.com/api/v2/referreroffer/YOUR_PARTNER_CODE?mm_e=923173becee4ec7b...9abe&nonce=11baf0cb...f061&order_number=253829&order_total=113&order_currency=GBP&situation=postpurchase">
</script>
```

Non-personal parameters (order details, situation) can remain unencrypted alongside the `mm_e` parameter.