Types - Grain Analytics

Every block on this page is copied from the .d.ts files of @grainql/tag 4.5.1 and @grainql/analytics-web 3.4.2. When a sentence on this site disagrees with a block here, the block wins. A field with ? is optional.

Grain Tag

import type {
  GrainTagConfig,
  GrainTagInstance,
  EventPayload,
  GrainEvent,
  ConsentMode,
  ConsentState,
  UTMParameters,
  FirstTouchAttribution,
  HeatmapClickData,
  HeatmapScrollData,
} from '@grainql/tag';

GrainTagConfig

The argument of init.

interface GrainTagConfig {
  tenantId: string;
  apiUrl?: string;
  debug?: boolean;
  version?: string;
  consentMode?: ConsentMode;
  enablePageViews?: boolean;
  enableHeatmaps?: boolean;
  enableSnapshots?: boolean;
  enableRescue?: boolean;
  enableDataLayer?: boolean;
  batchSize?: number;
  flushInterval?: number;
  retryAttempts?: number;
}

Field	Default	Meaning
`tenantId`	required	The tenant alias.
`apiUrl`	the production endpoint	The endpoint that receives events.
`debug`	`false`	Logs to the console.
`version`	none	Overrides the reported SDK version.
`consentMode`	`'auto'`	Read `ConsentMode` below.
`enablePageViews`	`true`	Sends a page view on every navigation.
`enableHeatmaps`	`true`	Records clicks and scroll depth.
`enableSnapshots`	`true`	Captures DOM snapshots.
`enableRescue`	`true`	Runs the rescue campaigns from the dashboard.
`enableDataLayer`	none	Reads `dataLayer` pushes through the connectors from the dashboard.
`batchSize`	`50`	Events per request.
`flushInterval`	`5000`	Milliseconds between automatic flushes.
`retryAttempts`	`3`	Retries for a failed request.

Read Configuration options.

GrainTagInstance

The return value of init and getInstance.

interface GrainTagInstance {
  track(eventName: string, properties?: Record<string, unknown>): void;
  identify(userId: string): void;
  consent: {
    grant(categories?: string[]): void;
    revoke(categories?: string[]): void;
    status(): ConsentState | null;
  };
  flush(): Promise<void>;
  destroy(): void;
  isReady(): boolean;
  updateDataLayerConnectors(connectors: DataLayerConnectorConfig[]): void;
}

Read Core methods.

DataLayerConnectorConfig

The element type of the updateDataLayerConnectors argument. The package does not export this name, so declare the shape in your own code when you need it.

interface DataLayerConnectorConfig {
  id: string;
  enabled: boolean;
  priority: number;
  include_patterns: string[];
  exclude_patterns: string[];
  include_dimensions: string[];
  exclude_dimensions: string[];
  event_name_transform: string;
  catch_all_unhandled: boolean;
  modifiers: string[];
}

EventPayload

The shape of one event on the wire.

interface EventPayload {
  eventName: string;
  userId: string;
  properties: Record<string, unknown>;
}

GrainEvent

An event before the SDK fills in the user ID and the timestamp.

interface GrainEvent {
  eventName: string;
  userId?: string;
  properties?: Record<string, unknown>;
  timestamp?: number;
}

ConsentMode

The value of consentMode in GrainTagConfig.

type ConsentMode = 'auto' | 'opt-in' | 'opt-out';

Value	Meaning
`'auto'`	Cookieless with a daily rotating ID. A grant switches to a permanent ID.
`'opt-in'`	Only necessary tracking until the user grants consent.
`'opt-out'`	Full tracking until the user revokes consent.

ConsentState

The return value of consent.status.

interface ConsentState {
  granted: boolean;
  categories: string[];
  timestamp: number;
  version: string;
}

Field	Meaning
`granted`	Whether consent is granted now.
`categories`	The granted categories, for example `['necessary', 'analytics']`.
`timestamp`	The Unix time of the decision, in milliseconds.
`version`	The version of the consent record.

UTMParameters

The UTM parameters of the current URL.

interface UTMParameters {
  utm_source?: string;
  utm_medium?: string;
  utm_campaign?: string;
  utm_term?: string;
  utm_content?: string;
}

FirstTouchAttribution

The stored source of the first visit.

interface FirstTouchAttribution {
  source: string;
  medium: string;
  campaign: string;
  referrer: string;
  referrer_category: string;
  timestamp: number;
}

HeatmapClickData

One recorded click.

interface HeatmapClickData {
  pageUrl: string;
  xpath: string;
  selector?: string;
  fingerprint?: string;
  relX?: number;
  relY?: number;
  viewportX: number;
  viewportY: number;
  pageX: number;
  pageY: number;
  elementTag: string;
  elementText?: string;
  timestamp: number;
  deviceType: 'mobile' | 'desktop';
  isNestedScroll?: boolean;
  scrollContainerId?: string;
}

HeatmapScrollData

One recorded scroll segment.

interface HeatmapScrollData {
  pageUrl: string;
  scrollDepthPx: number;
  scrollDepthPercent: number;
  viewportSection: number;
  durationMs: number;
  entryTimestamp: number;
  exitTimestamp: number;
  pageHeight: number;
  viewportHeight: number;
  deviceType: 'mobile' | 'desktop';
  isSplit?: boolean;
  maxViewportSection?: number;
  isNestedScroll?: boolean;
  scrollContainerId?: string;
}

Analytics Web

import type {
  GrainConfig,
  GrainEvent,
  EventPayload,
  AuthStrategy,
  AuthProvider,
  ConsentMode,
  ConsentState,
  CookieConfig,
  SendEventOptions,
  SetPropertyOptions,
  LoginOptions,
  PropertyPayload,
  RemoteConfigRequest,
  RemoteConfigResponse,
  RemoteConfigOptions,
  RemoteConfigCache,
  ConfigChangeListener,
  ReferrerCategory,
  UTMParameters,
  FirstTouchAttribution,
  InteractionConfig,
  SectionConfig,
  AutoTrackingConfig,
  SectionViewData,
  SectionTrackingOptions,
  ErrorDigest,
  FormattedError,
} from '@grainql/analytics-web';

The template event property types are on Template methods.

GrainConfig

The argument of new GrainAnalytics and createGrainAnalytics.

interface GrainConfig {
  tenantId: string;
  apiUrl?: string;
  authStrategy?: AuthStrategy;
  secretKey?: string;
  authProvider?: AuthProvider;
  userId?: string;
  batchSize?: number;
  flushInterval?: number;
  retryAttempts?: number;
  retryDelay?: number;
  maxEventsPerRequest?: number;
  debug?: boolean;
  defaultConfigurations?: Record<string, string>;
  configCacheKey?: string;
  configRefreshInterval?: number;
  enableConfigCache?: boolean;
  consentMode?: ConsentMode;
  waitForConsent?: boolean;
  disableAutoProperties?: boolean;
  allowedProperties?: string[];
  enableHeartbeat?: boolean;
  heartbeatActiveInterval?: number;
  heartbeatInactiveInterval?: number;
  enableAutoPageView?: boolean;
  stripQueryParams?: boolean;
  stripHash?: boolean;
  enableHeatmapTracking?: boolean;
}

Every field, its default, and its meaning are on Configuration options.

GrainEvent

The object form of track.

interface GrainEvent {
  eventName: string;
  userId?: string;
  properties?: Record<string, unknown>;
  timestamp?: Date;
}

The Grain Tag GrainEvent has a number timestamp. The Analytics Web GrainEvent has a Date timestamp.

EventPayload

The shape of one event on the wire.

interface EventPayload {
  eventName: string;
  userId: string;
  properties: Record<string, unknown>;
}

AuthStrategy

The value of authStrategy in GrainConfig and LoginOptions.

type AuthStrategy = 'NONE' | 'SERVER_SIDE' | 'JWT';

Read Authentication.

AuthProvider

The object that supplies the JWT for the JWT strategy.

interface AuthProvider {
  getToken(): Promise<string> | string;
}

ConsentMode

The value of consentMode in GrainConfig.

type ConsentMode = 'COOKIELESS' | 'GDPR_STRICT' | 'GDPR_OPT_OUT';

Value	Meaning
`'COOKIELESS'`	Daily rotating IDs. No consent is required.
`'GDPR_STRICT'`	A permanent ID only after consent. Without consent the client stays cookieless.
`'GDPR_OPT_OUT'`	A permanent ID by default. The client switches to cookieless when the user opts out.

ConsentState

The return value of getConsentState, and the argument of a consent listener.

interface ConsentState {
  granted: boolean;
  categories: string[];
  timestamp: Date;
  version: string;
}

The Grain Tag ConsentState has a number timestamp. The Analytics Web ConsentState has a Date timestamp.

CookieConfig

The options of the cookie that holds the permanent ID.

interface CookieConfig {
  domain?: string;
  path?: string;
  sameSite?: 'strict' | 'lax' | 'none';
  secure?: boolean;
  maxAge?: number;
}

SendEventOptions

The last argument of track and of every template method.

interface SendEventOptions {
  flush?: boolean;
}

SetPropertyOptions

The last argument of setProperty.

interface SetPropertyOptions {
  userId?: string;
}

LoginOptions

The argument of login.

interface LoginOptions {
  userId?: string;
  authToken?: string;
  authStrategy?: AuthStrategy;
}

PropertyPayload

The shape of a setProperty request on the wire. Every value is a string.

interface PropertyPayload {
  userId: string;
  [key: string]: string;
}

RemoteConfigRequest

The shape of a configuration request on the wire.

interface RemoteConfigRequest {
  userId: string;
  immediateKeys: string[];
  properties?: Record<string, string>;
  currentUrl?: string;
}

RemoteConfigOptions

The options argument of getConfigAsync, getAllConfigsAsync, and fetchConfig.

interface RemoteConfigOptions {
  immediateKeys?: string[];
  properties?: Record<string, string>;
  userId?: string;
  forceRefresh?: boolean;
  currentUrl?: string;
}

The field table is on Configuration methods.

RemoteConfigResponse

The return value of fetchConfig.

interface RemoteConfigResponse {
  userId: string;
  snapshotId: string;
  configurations: Record<string, string>;
  isFinal: boolean;
  qualifiedSegments: string[];
  qualifiedRuleSets: string[];
  timestamp: string;
  isFromCache: boolean;
  autoTrackingConfig?: {
    interactions: Array<{
      eventName: string;
      description: string;
      selector: string;
      priority: number;
      label: string;
    }>;
    sections: Array<{
      sectionName: string;
      description: string;
      sectionType: string;
      selector: string;
      importance: number;
    }>;
  };
}

RemoteConfigCache

The record that the client stores under configCacheKey in localStorage.

interface RemoteConfigCache {
  configurations: Record<string, string>;
  snapshotId: string;
  timestamp: string;
  userId: string;
}

ConfigChangeListener

The argument of addConfigChangeListener and removeConfigChangeListener.

type ConfigChangeListener = (configurations: Record<string, string>) => void;

ReferrerCategory

The category that the client assigns to a referrer.

type ReferrerCategory = 'organic' | 'paid' | 'social' | 'direct' | 'email' | 'referral';

UTMParameters

The UTM parameters of the current URL.

interface UTMParameters {
  utm_source?: string;
  utm_medium?: string;
  utm_campaign?: string;
  utm_term?: string;
  utm_content?: string;
}

FirstTouchAttribution

The stored source of the first visit.

interface FirstTouchAttribution {
  source: string;
  medium: string;
  campaign: string;
  referrer: string;
  referrer_category: ReferrerCategory;
  timestamp: number;
}

InteractionConfig

One automatic interaction tracker from the dashboard.

interface InteractionConfig {
  eventName: string;
  description: string;
  selector: string;
  priority: number;
  label: string;
}

SectionConfig

One automatic section tracker from the dashboard.

interface SectionConfig {
  sectionName: string;
  description: string;
  sectionType: string;
  selector: string;
  importance: number;
}

AutoTrackingConfig

The automatic tracking definition that the API returns.

interface AutoTrackingConfig {
  interactions: InteractionConfig[];
  sections: SectionConfig[];
}

SectionViewData

One recorded section view.

interface SectionViewData {
  sectionName: string;
  sectionType: string;
  entryTime: number;
  exitTime: number;
  duration: number;
  viewportWidth: number;
  viewportHeight: number;
  scrollDepth: number;
  visibleAreaPercentage: number;
  scrollSpeedAtEntry?: number;
  scrollSpeedAtExit?: number;
}

SectionTrackingOptions

The thresholds that decide when a section view counts. Read Attention quality.

interface SectionTrackingOptions {
  minDwellTime: number;
  scrollVelocityThreshold: number;
  intersectionThreshold: number;
  debounceDelay: number;
  batchDelay: number;
  debug?: boolean;
  maxSectionDuration?: number;
  minScrollDistance?: number;
  idleThreshold?: number;
}

ErrorDigest

The summary of the events in a failed request.

interface ErrorDigest {
  eventCount: number;
  totalProperties: number;
  totalSize: number;
  eventNames: string[];
  userIds: string[];
}

FormattedError

The record that the client logs when a request fails. Read Errors and retries.

interface FormattedError {
  code: string;
  message: string;
  digest: ErrorDigest;
  timestamp: string;
  context: string;
  originalError?: unknown;
}

React

import type {
  GrainProviderProps,
  UseConfigOptions,
  UseConfigResult,
  UseAllConfigsOptions,
  UseAllConfigsResult,
  TrackFunction,
  ConsentBannerProps,
  PrivacyPreferenceCenterProps,
  CookieNoticeProps,
  PrivacyPreferences,
  DataDeletionOptions,
} from '@grainql/analytics-web/react';

GrainProviderProps

The props of GrainProvider.

interface GrainProviderProps {
  children: React.ReactNode;
  client?: GrainAnalytics;
  config?: GrainConfig;
}

UseConfigOptions

The options argument of useConfig.

interface UseConfigOptions {
  forceRefresh?: boolean;
  immediateKeys?: string[];
  properties?: Record<string, string>;
}

UseConfigResult

The return value of useConfig.

interface UseConfigResult {
  value: string | undefined;
  isRefreshing: boolean;
  error: Error | null;
  refresh: () => Promise<void>;
}

UseAllConfigsOptions

The options argument of useAllConfigs.

interface UseAllConfigsOptions {
  forceRefresh?: boolean;
  immediateKeys?: string[];
  properties?: Record<string, string>;
}

UseAllConfigsResult

The return value of useAllConfigs.

interface UseAllConfigsResult {
  configs: Record<string, string>;
  isRefreshing: boolean;
  error: Error | null;
  refresh: () => Promise<void>;
}

TrackFunction

The return value of useTrack.

type TrackFunction = (
  eventName: string,
  properties?: Record<string, unknown>,
  options?: SendEventOptions
) => Promise<void>;

ConsentBannerProps

The props of ConsentBanner.

interface ConsentBannerProps {
  position?: 'top' | 'bottom' | 'center';
  theme?: 'light' | 'dark' | 'glass';
  customText?: string;
  onAccept?: () => void;
  onDecline?: () => void;
  showPreferences?: boolean;
  privacyPolicyUrl?: string;
}

PrivacyPreferenceCenterProps

The props of PrivacyPreferenceCenter.

interface PrivacyPreferenceCenterProps {
  isOpen: boolean;
  onClose: () => void;
  onSave?: (categories: string[]) => void;
}

CookieNoticeProps

The props of CookieNotice.

interface CookieNoticeProps {
  message?: string;
  privacyPolicyUrl?: string;
  onDismiss?: () => void;
  position?: 'top' | 'bottom';
}

PrivacyPreferences

The preferences field of usePrivacyPreferences.

interface PrivacyPreferences {
  necessary: boolean;
  analytics: boolean;
  functional: boolean;
}

DataDeletionOptions

The argument of useDataDeletion.

interface DataDeletionOptions {
  apiUrl: string;
  tenantId: string;
  onSuccess?: (message: string) => void;
  onError?: (error: string) => void;
}

Read React hooks for the hook and component signatures.

​Grain Tag

​GrainTagConfig

​GrainTagInstance

​DataLayerConnectorConfig

​EventPayload

​GrainEvent

​ConsentMode

​ConsentState

​UTMParameters

​FirstTouchAttribution

​HeatmapClickData

​HeatmapScrollData

​Analytics Web

​GrainConfig

​GrainEvent

​EventPayload

​AuthStrategy

​AuthProvider

​ConsentMode

​ConsentState

​CookieConfig

​SendEventOptions

​SetPropertyOptions

​LoginOptions

​PropertyPayload

​RemoteConfigRequest

​RemoteConfigOptions

​RemoteConfigResponse

​RemoteConfigCache

​ConfigChangeListener

​ReferrerCategory

​UTMParameters

​FirstTouchAttribution

​InteractionConfig

​SectionConfig

​AutoTrackingConfig

​SectionViewData

​SectionTrackingOptions

​ErrorDigest

​FormattedError

​React

​GrainProviderProps

​UseConfigOptions

​UseConfigResult

​UseAllConfigsOptions

​UseAllConfigsResult

​TrackFunction

​ConsentBannerProps

​PrivacyPreferenceCenterProps

​CookieNoticeProps

​PrivacyPreferences

​DataDeletionOptions

Grain Tag

GrainTagConfig

GrainTagInstance

DataLayerConnectorConfig

EventPayload

GrainEvent

ConsentMode

ConsentState

UTMParameters

FirstTouchAttribution

HeatmapClickData

HeatmapScrollData

Analytics Web

GrainConfig

GrainEvent

EventPayload

AuthStrategy

AuthProvider

ConsentMode

ConsentState

CookieConfig

SendEventOptions

SetPropertyOptions

LoginOptions

PropertyPayload

RemoteConfigRequest

RemoteConfigOptions

RemoteConfigResponse

RemoteConfigCache

ConfigChangeListener

ReferrerCategory

UTMParameters

FirstTouchAttribution

InteractionConfig

SectionConfig

AutoTrackingConfig

SectionViewData

SectionTrackingOptions

ErrorDigest

FormattedError

React

GrainProviderProps

UseConfigOptions

UseConfigResult

UseAllConfigsOptions

UseAllConfigsResult

TrackFunction

ConsentBannerProps

PrivacyPreferenceCenterProps

CookieNoticeProps

PrivacyPreferences

DataDeletionOptions