@capgo/capacitor-contentsquare

Add Contentsquare analytics and Session Replay to your Capacitor app with the official Contentsquare SDKs, packaged for Capacitor 8 with Swift Package Manager support.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-contentsquare in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-contentsquare to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Consent: optIn() starts tracking and optOut() stops it and clears local state.
• Screen views: sendScreenName() sends a screenview for the current screen.
• Transactions and variables: sendTransaction() and sendDynamicVar().
• Session Replay privacy: setPIISelectors(), setCapturedElementsSelector() and excludeURLForReplay() control what is recorded.
• Official SDKs: wraps the Contentsquare iOS and Android libraries.
• Platforms: iOS and Android. Not available on web.

Capacitor 8 wrapper for the official Contentsquare mobile SDKs.

This package keeps the official Contentsquare Capacitor API shape while updating the plugin packaging for Capacitor 8, Swift Package Manager, and Capgo's standard plugin template.

Documentation

The upstream product documentation is available at docs.contentsquare.com/en/capacitor/.

Compatibility

| Plugin version | Capacitor compatibility | Native iOS SDK | Native Android SDK | | -------------- | ----------------------- | -------------- | ------------------ | | v8.. | v8.. | 4.52.4 | 4.52.4 |

This is a community Capacitor 8 port. Contentsquare's official package currently targets Capacitor 7, but the documented API surface remains the same.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-contentsquare` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-contentsquare
bunx cap sync

Usage

import { ContentsquarePlugin, CurrencyCode } from '@capgo/capacitor-contentsquare';

await ContentsquarePlugin.optIn();

await ContentsquarePlugin.sendScreenName('Home');

await ContentsquarePlugin.sendTransaction({
  transactionValue: 10,
  transactionCurrency: CurrencyCode.EUR,
  transactionId: 'order-42',
});

await ContentsquarePlugin.sendDynamicVar({
  dynVarKey: 'store',
  dynVarValue: 'rome',
});

iOS Setup

To enable Contentsquare in-app features on iOS, your host app still needs the upstream deeplink wiring described in the official docs:

1. Add the cs-$(PRODUCT_BUNDLE_IDENTIFIER) URL scheme to the app.
2. Forward incoming Contentsquare URLs with Contentsquare.handle(url: url) from your AppDelegate, SceneDelegate, or SwiftUI onOpenURL.

API

• optIn()
• optOut()
• sendScreenName(...)
• sendTransaction(...)
• sendDynamicVar(...)
• excludeURLForReplay(...)
• setPIISelectors(...)
• setCapturedElementsSelector(...)
• Interfaces
• Enums

Public Contentsquare API for Capacitor applications.

optIn()

optIn() => Promise<void>

Marks the user as opted in and starts tracking.

optOut()

optOut() => Promise<void>

Stops tracking, clears local Contentsquare state, and opts the user out.

sendScreenName(...)

sendScreenName(name: string) => Promise<void>

Sends a screenview event for the current screen.

| Param | Type | | ---------- | ------------------- | | name | string |

sendTransaction(...)

sendTransaction(transactionItem: TransactionItem) => Promise<void>

Sends a transaction to Contentsquare.

| Param | Type | | --------------------- | ----------------------------------------------------------- | | transactionItem | TransactionItem |

sendDynamicVar(...)

sendDynamicVar(dynamicVarItem: DynamicVarItem) => Promise<void>

Sends a dynamic variable.

The value must be either a string or a non-negative integer.

| Param | Type | | -------------------- | --------------------------------------------------------- | | dynamicVarItem | DynamicVarItem |

excludeURLForReplay(...)

excludeURLForReplay(url: string) => Promise<void>

Excludes URLs matching the provided JavaScript regular expression literal from Session Replay.

Example: "/checkout/".

| Param | Type | | --------- | ------------------- | | url | string |

setPIISelectors(...)

setPIISelectors(pii: PIIConfig) => Promise<void>

Applies Session Replay masking rules to specific selectors and attributes.

| Param | Type | | --------- | ----------------------------------------------- | | pii | PIIConfig |

setCapturedElementsSelector(...)

setCapturedElementsSelector(elements: string) => Promise<void>

Allows specific elements to be captured even when the current page is masked.

| Param | Type | | -------------- | ------------------- | | elements | string |

Interfaces

TransactionItem

Transaction payload sent to Contentsquare.

| Prop | Type | Description | | ------------------------- | ------------------- | -------------------------------- | | transactionValue | number | Transaction value. | | transactionCurrency | string | ISO 4217 currency code. | | transactionId | string | Optional transaction identifier. |

DynamicVarItem

Dynamic variable payload.

| Prop | Type | Description | | ----------------- | ----------------------------- | ---------------------------------------------------------------------- | | dynVarKey | string | Contentsquare dynamic variable key. | | dynVarValue | string | number | Dynamic variable value. Use either a string or a non-negative integer. |

PIIConfig

Selector and attribute masking configuration for Session Replay.

| Prop | Type | Description | | ------------------ | --------------------------- | ----------------------------------------------- | | PIISelectors | string[] | CSS selectors whose content must be masked. | | Attributes | PIIAttribute[] | Attribute masking rules for specific selectors. |

PIIAttribute

Attribute masking rule used by setPIISelectors.

| Prop | Type | Description | | -------------- | ------------------------------- | ------------------------------------------------------ | | selector | string | CSS selector to match. | | attrName | string | string[] | Attribute name or names to mask for matching elements. |

Enums

CurrencyCode

| Members | Value | | --------- | ------------------ | | USD | 'USD' | | CAD | 'CAD' | | EUR | 'EUR' | | AED | 'AED' | | AFN | 'AFN' | | ALL | 'ALL' | | AMD | 'AMD' | | ARS | 'ARS' | | AUD | 'AUD' | | AZN | 'AZN' | | BAM | 'BAM' | | BDT | 'BDT' | | BGN | 'BGN' | | BHD | 'BHD' | | BIF | 'BIF' | | BND | 'BND' | | BOB | 'BOB' | | BRL | 'BRL' | | BWP | 'BWP' | | BYN | 'BYN' | | BZD | 'BZD' | | CDF | 'CDF' | | CHF | 'CHF' | | CLP | 'CLP' | | CNY | 'CNY' | | COP | 'COP' | | CRC | 'CRC' | | CVE | 'CVE' | | CZK | 'CZK' | | DJF | 'DJF' | | DKK | 'DKK' | | DOP | 'DOP' | | DZD | 'DZD' | | EEK | 'EEK' | | EGP | 'EGP' | | ERN | 'ERN' | | ETB | 'ETB' | | GBP | 'GBP' | | GEL | 'GEL' | | GHS | 'GHS' | | GNF | 'GNF' | | GTQ | 'GTQ' | | HKD | 'HKD' | | HNL | 'HNL' | | HRK | 'HRK' | | HUF | 'HUF' | | IDR | 'IDR' | | ILS | 'ILS' | | INR | 'INR' | | IQD | 'IQD' | | IRR | 'IRR' | | ISK | 'ISK' | | JMD | 'JMD' | | JOD | 'JOD' | | JPY | 'JPY' | | KES | 'KES' | | KHR | 'KHR' | | KMF | 'KMF' | | KRW | 'KRW' | | KWD | 'KWD' | | KZT | 'KZT' | | LBP | 'LBP' | | LKR | 'LKR' | | LTL | 'LTL' | | LVL | 'LVL' | | LYD | 'LYD' | | MAD | 'MAD' | | MDL | 'MDL' | | MGA | 'MGA' | | MKD | 'MKD' | | MMK | 'MMK' | | MOP | 'MOP' | | MUR | 'MUR' | | MXN | 'MXN' | | MYR | 'MYR' | | MZN | 'MZN' | | NAD | 'NAD' | | NGN | 'NGN' | | NIO | 'NIO' | | NOK | 'NOK' | | NPR | 'NPR' | | NZD | 'NZD' | | OMR | 'OMR' | | PAB | 'PAB' | | PEN | 'PEN' | | PHP | 'PHP' | | PKR | 'PKR' | | PLN | 'PLN' | | PYG | 'PYG' | | QAR | 'QAR' | | RON | 'RON' | | RSD | 'RSD' | | RUB | 'RUB' | | RWF | 'RWF' | | SAR | 'SAR' | | SDG | 'SDG' | | SEK | 'SEK' | | SGD | 'SGD' | | SOS | 'SOS' | | SYP | 'SYP' | | THB | 'THB' | | TND | 'TND' | | TOP | 'TOP' | | TRY | 'TRY' | | TTD | 'TTD' | | TWD | 'TWD' | | TZS | 'TZS' | | UAH | 'UAH' | | UGX | 'UGX' | | UYU | 'UYU' | | UZS | 'UZS' | | VEF | 'VEF' | | VND | 'VND' | | XAF | 'XAF' | | XOF | 'XOF' | | YER | 'YER' | | ZAR | 'ZAR' | | ZMK | 'ZMK' | | ZWL | 'ZWL' |