@capgo/capacitor-contentsquare

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.45.4 | 4.43.3 |

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

Install

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' |