SDK Legacy Guide

import { Ninetailed } from '@ninetailed/experience.js';

const ninetailed = new Ninetailed(
  // First argument: NinetailedApiClientOptions OR NinetailedApiClient instance
  {
    clientId: string,           // Required: API key
    environment?: string,       // Default: 'main'
    preview?: boolean,          // Enable preview mode
  },
  // Second argument: Options
  {
    url?: string,                              // Override API base URL
    locale?: Locale,                           // Language locale string
    plugins?: (NinetailedPlugin | NinetailedPlugin[])[], // Plugins (nested arrays flattened)
    requestTimeout?: number,                   // Timeout for API requests
    onLog?: OnLogHandler,                      // Custom log handler
    onError?: OnErrorHandler,                  // Custom error handler
    componentViewTrackingThreshold?: number,   // Default: 2000 (ms)
    componentHoverTrackingThreshold?: number,  // Default: 2000 (ms)
    onInitProfileId?: OnInitProfileId,         // Callback when profile ID is first initialized
    buildClientContext?: () => NinetailedRequestContext, // Custom context builder
    storageImpl?: Storage,                     // Custom storage ({ getItem, setItem, removeItem })
  }
);

await ninetailed.page({ url: '/some-page', title: 'My Page' });

await ninetailed.track('button_click', { buttonId: 'cta-hero' });

await ninetailed.identify('user-123', { plan: 'enterprise', role: 'admin' });

await ninetailed.batch([
  { type: 'page', properties: {} },
  { type: 'track', event: 'signup', properties: {} },
]);

const unsubscribe = ninetailed.onProfileChange((profileState) => {
  if (profileState.status === 'success') {
    console.log('Profile:', profileState.profile);
    console.log('Experiences:', profileState.experiences);
  }
});

// ObserveOptions:
{ delay?: number, trackClicks?: boolean, trackHovers?: boolean }

type ProfileState =
  | { status: 'loading'; profile: null; experiences: null; changes: null; error: null; from: 'api' | 'hydrated' }
  | {
      status: 'success';
      profile: Profile;
      experiences: SelectedVariantInfo[];
      changes: Change[];
      error: null;
      from: 'api' | 'hydrated';
    }
  | {
      status: 'error';
      profile: Profile | null;
      experiences: SelectedVariantInfo[] | null;
      changes: Change[] | null;
      error: Error;
      from: 'api' | 'hydrated';
    };

// Instantiation mode (creates Ninetailed internally)
type NinetailedProviderInstantiationProps = {
  clientId: string;
  environment?: string;
  preview?: boolean;
  url?: string;
  plugins?: (NinetailedPlugin | NinetailedPlugin[])[];
  locale?: Locale;
  requestTimeout?: number;
  onLog?: OnLogHandler;
  onError?: OnErrorHandler;
  componentViewTrackingThreshold?: number;
  componentHoverTrackingThreshold?: number;
  buildClientContext?: () => NinetailedRequestContext;
  onInitProfileId?: OnInitProfileId;
  storageImpl?: Storage;
};

// Instance mode (pass a pre-created Ninetailed)
type NinetailedProviderProps = NinetailedProviderInstantiationProps | { ninetailed: Ninetailed };

const { track, identify, page, reset, debug, profileState } = useNinetailed();

type UseProfileHookResult = Omit<ProfileState, 'experiences'> & {
  loading: boolean; // true when status === 'loading'
};

const { profile, loading, status, error } = useProfile();
if (loading) return <Spinner />;
console.log(profile.traits, profile.location, profile.audiences);

const { status, hasVariants, experience, variant, variantIndex, audience, isPersonalized, profile, error } =
  useExperience({ baseline, experiences });

type FlagResult<T> =
  | { status: 'loading'; value: T; error: null }
  | { status: 'success'; value: T; error: null }
  | { status: 'error'; value: T; error: Error };

type UseFlagOptions = {
  shouldAutoTrack?: boolean | (() => boolean); // default: true
};

const { status, value, error } = useFlag('banner-text', 'default text');
const { value: config } = useFlag<{ padding: string; color: string }>('hero-config', {
  padding: '10px',
  color: 'blue',
});

const [flag, track] = useFlagWithManualTracking<{
  padding: string;
  color: string;
}>('testing-component-tracking', { padding: '10px', color: 'blue' });

const handleClick = () => {
  track();
  // ... user interaction
};

const { loading, variant, isPersonalized, audience } = usePersonalize(
  baseline,
  variants,
  { holdout: -1 }, // holdout percentage (-1 = disabled)
);

type ExperienceProps<P, PassThroughProps, Variant> = {
  id: string; // Required: baseline entry ID
  experiences: ExperienceConfiguration<Variant>[]; // Mapped experiences
  component: ComponentType<P>; // The component to render
  loadingComponent?: ExperienceLoadingComponent; // Custom loading component
  passthroughProps?: PassThroughProps; // Props passed regardless of variant
  trackClicks?: boolean; // Enable click tracking
  trackHovers?: boolean; // Enable hover tracking
  // ...all other baseline props spread
};

<Experience
  {...entry.fields}
  id={entry.sys.id}
  component={ComponentRenderer}
  experiences={mappedExperiences}
  trackClicks
  trackHovers
  loadingComponent={ESRLoadingComponent}
/>

type ESRProviderProps = {
  experienceVariantsMap: Record<string, number>; // experienceId -> variantIndex
};

type PersonalizeProps<P> = P & {
  id: string;
  variants?: Variant<P>[];
  component: PersonalizedComponent<P>;
  loadingComponent?: React.ComponentType;
  holdout?: number; // default: -1
};

type MergeTagProps = {
  id: string; // Trait path (e.g. 'traits_company' or 'location_city')
  fallback?: string; // Fallback value if trait not found
};

<MergeTag id="traits_firstName" fallback="there" />
// Renders: profile.traits.firstName or "there"

<EntryAnalytics
  {...entry}
  id={entry.id}
  component={MyComponent}
  trackClicks
/>

type Variant<P = unknown> = P & {
  id: string;
  audience: { id: string };
};

type NextNinetailedProviderProps = NinetailedProviderProps & {
  onRouteChange?: OnRouteChange;
};

type OnRouteChange = (routeInfo: { isInitialRoute: boolean }, ninetailed: NinetailedInstance) => void;

// Input: "expId1=1,expId2=2"
// Output: { expId1: 1, expId2: 2 }
decodeExperienceVariantsMap('expId1=1,expId2=2');

const apiClient = new NinetailedApiClient({
  clientId: string,
  environment?: string,     // Default: 'main'
  url?: string,             // Override base URL
  fetchImpl?: FetchImpl,    // Custom fetch for non-browser environments
});

type RequestOptions = {
  timeout?: number; // Default: 3000ms
  preflight?: boolean; // ESR/SSR mode: evaluate but don't persist
  locale?: string;
  ip?: string; // Override IP for server-side calls
  plainText?: boolean; // Default: true. Avoids CORS preflight
  retries?: number; // Default: 1. Only retries 503s
  minRetryTimeout?: number; // Default: 0ms
  enabledFeatures?: Feature[]; // 'ip-enrichment' | 'location'
};

import { buildPageEvent, buildTrackEvent, buildIdentifyEvent } from '@ninetailed/experience.js-shared';

buildPageEvent({ messageId, timestamp, ctx, location?, properties });
buildTrackEvent({ messageId, timestamp, ctx, location?, event, properties });
buildIdentifyEvent({ messageId, timestamp, ctx, location?, userId, traits });

{
  url: string;
  referrer: string;
  locale: string;
  userAgent: string;
  document?: { title: string };
}

type Profile = {
  id: string;
  stableId: string;
  random: number; // 0-1, used for traffic allocation
  audiences: string[]; // Array of matched audience IDs
  traits: Traits; // JSON object of user traits
  location: GeoLocation;
  session: SessionStatistics;
};

type GeoLocation = {
  coordinates?: { latitude: number; longitude: number };
  city?: string;
  postalCode?: string;
  region?: string;
  regionCode?: string;
  country?: string;
  countryCode?: Alpha2Code;
  continent?: string;
  timezone?: string;
};

type ExperienceConfiguration<Variant extends Reference = Reference> = {
  id: string;
  type: 'nt_personalization' | 'nt_experiment';
  name?: string;
  description?: string;
  audience?: { id: string; name?: string; description?: string };
  trafficAllocation: number;
  distribution: Distribution[];
  sticky?: boolean;
  components: (EntryReplacement<Variant> | InlineVariable)[];
};

type SelectedVariantInfo = {
  experienceId: string;
  variantIndex: number;
  variants: Record<string, string>;
  sticky: boolean;
};

type Change = {
  type: 'Variable';
  key: string;
  value: string | boolean | number | JsonObject;
  meta: { experienceId: string; variantIndex: number };
};

ExperienceMapper.mapCustomExperience(ctfExperience, (variant) => ({
  id: variant.sys.id,
  ...variant.fields,
}));

const experiences = ExperienceMapper.mapBaselineWithExperiences(heroEntry);

import { ExperienceMapper } from '@ninetailed/experience.js-utils-contentful';

const experiences = (entry.fields.nt_experiences || [])
  .filter(ExperienceMapper.isExperienceEntry)
  .map(ExperienceMapper.mapExperience);

new NinetailedInsightsPlugin({ url?: string })

new NinetailedPreviewPlugin({
  experiences: ExperienceConfiguration[],           // All available experiences
  audiences: ExposedAudienceDefinition[],          // All available audiences
  onOpenExperienceEditor?: (experience) => void,   // Callback to open experience editor
  onOpenAudienceEditor?: (audience) => void,       // Callback to open audience editor
  url?: string,                                     // Preview bridge URL override
  nonce?: string,                                   // CSP nonce for script/style injection
  ui?: { opener: { hide: boolean } },              // Widget UI options
})

const preview = process.env.NODE_ENV !== 'production';
plugins={[
  ...(preview ? [new NinetailedPreviewPlugin({ ... })] : []),
]}

new NinetailedSsrPlugin({
  cookie?: {
    domain?: string,      // Cookie domain
    expires?: number,     // Days until expiry (default: 365)
  }
})

new NinetailedPrivacyPlugin(
  config?: Partial<PrivacyConfig>,              // Config when consent NOT given
  acceptedConsentConfig?: Partial<PrivacyConfig> // Config when consent IS given (SDK >= 7.7)
)

type PrivacyConfig = {
  allowedEvents: EventType[]; // Default no-consent: ['page']
  allowedPageEventProperties: string[]; // Default: ['*']
  allowedTrackEvents: string[]; // Default: []
  allowedTrackEventProperties: string[]; // Default: []
  allowedTraits: string[]; // Default: []
  blockProfileMerging: boolean; // Default: true
  enabledFeatures: Feature[]; // Default: []
};

window.ninetailed.consent(true); // Grant consent
window.ninetailed.consent(false); // Revoke consent

{
  event: 'nt_experience',
  ninetailed_variant: '{{selectedVariantSelector}}',
  ninetailed_experience: '{{experience.id}}',
  ninetailed_experience_name: '{{experience.name}}',
  ninetailed_audience: '{{audience.id}}',
  ninetailed_component: '{{selectedVariant.id}}',
}

// GTM
new NinetailedGoogleTagmanagerPlugin({ template?: Template })

// Segment
new NinetailedSegmentPlugin({ analytics?: AnalyticsBrowserLike, template?: Template })

// Contentsquare
new NinetailedContentsquarePlugin({ actionTemplate?: string })

interface NinetailedInstance {
  page: Page;
  track: Track;
  trackComponentView: TrackComponentView;
  trackVariableComponentView: TrackVariableComponentView;
  identify: Identify;
  batch: Batch;
  reset: Reset;
  debug: Debug;
  profileState: ProfileState;
  onProfileChange: OnProfileChange;
  onChangesChange: OnChangesChange;
  plugins: NinetailedPlugin[];
  logger: Logger;
  eventBuilder: EventBuilder;
  onIsInitialized: OnIsInitialized;
  observeElement: ObserveElement;
  unobserveElement: UnObserveElement;
  onSelectVariant: OnSelectVariant;
}

type Storage = {
  getItem: (key: string) => any;
  setItem: (key: string, value: any) => void;
  removeItem: (key: string) => void;
};

type NinetailedRequestContext = {
  url: string;
  referrer: string;
  locale: string;
  userAgent: string;
  document?: { title: string };
};

type SessionStatistics = {
  id: string;
  isReturningVisitor: boolean;
  landingPage: Page;
  count: number;
  activeSessionLength: number;
  averageSessionLength: number;
};

type ProfileWithSelectedVariants = {
  profile: Profile;
  experiences: SelectedVariantInfo[];
  changes: Change[];
};

type Event =
  | PageviewEvent
  | TrackEvent
  | IdentifyEvent
  | ScreenEvent
  | ComponentViewEvent
  | ComponentClickEvent
  | ComponentHoverEvent;

type EventType = 'page' | 'track' | 'identify' | 'screen' | 'component' | 'component_click' | 'component_hover';

enum ComponentTypeEnum {
  EntryReplacement = 'EntryReplacement',
  InlineVariable = 'InlineVariable',
}

type EntryReplacement<Variant extends Reference> = {
  type: ComponentTypeEnum.EntryReplacement;
  baseline: Baseline;
  variants: (Variant | VariantRef)[];
};

type InlineVariable = {
  type: ComponentTypeEnum.InlineVariable;
  key: string;
  valueType: 'String' | 'Object' | 'Boolean' | 'Number';
  baseline: { value: AllowedVariableType };
  variants: { value: AllowedVariableType }[];
};

type AllowedVariableType = string | boolean | number | JsonObject;

import { NinetailedAPIClient } from '@ninetailed/experience.js-node';

const apiClient = new NinetailedAPIClient({
  clientId: 'YOUR_API_KEY',
  environment: 'YOUR_NINETAILED_ENV',
});

apiClient.sendTrackEvent(id, eventName, properties?, options?);
apiClient.sendIdentifyEvent(id, traits, options?);
apiClient.getProfile(id, options?);

// Cookie name for anonymous ID persistence (SSR plugin)
const NINETAILED_ANONYMOUS_ID_COOKIE = '__ninetailed_preview_id';

// Experience trait prefix
const EXPERIENCE_TRAIT_PREFIX = 'nt_experiment_';