Variable MergeTagValueResolverConst

Type Declaration

• getValueFromProfile: function

  • getValueFromProfile(
        id: string,
        profile?: {
            audiences: string[];
            id: string;
            location: {
                city?: string;
                continent?: string;
                coordinates?: { latitude: number; longitude: number };
                country?: string;
                countryCode?: string;
                postalCode?: string;
                region?: string;
                regionCode?: string;
                timezone?: string;
            };
            random: number;
            session: {
                activeSessionLength: number;
                averageSessionLength: number;
                count: number;
                id: string;
                isReturningVisitor: boolean;
                landingPage: {
                    path: string;
                    query: Record<string, string>;
                    referrer: string;
                    search: string;
                    title?: string;
                    url: string;
                    [key: string]: JSONType;
                };
            };
            stableId: string;
            traits: Record<string, JSONType>;
        },
    ): string
    | undefined

    Look up a merge-tag value from a profile using normalized selectors.

    Parameters

    • id: string

      Merge-tag identifier.

    • Optionalprofile: {
          audiences: string[];
          id: string;
          location: {
              city?: string;
              continent?: string;
              coordinates?: { latitude: number; longitude: number };
              country?: string;
              countryCode?: string;
              postalCode?: string;
              region?: string;
              regionCode?: string;
              timezone?: string;
          };
          random: number;
          session: {
              activeSessionLength: number;
              averageSessionLength: number;
              count: number;
              id: string;
              isReturningVisitor: boolean;
              landingPage: {
                  path: string;
                  query: Record<string, string>;
                  referrer: string;
                  search: string;
                  title?: string;
                  url: string;
                  [key: string]: JSONType;
              };
          };
          stableId: string;
          traits: Record<string, JSONType>;
      }

      Profile from which to resolve the value.

      • audiences: string[]

        List of audience identifiers that this profile belongs to.

      • id: string

        Primary identifier of the profile.

      • location: {
            city?: string;
            continent?: string;
            coordinates?: { latitude: number; longitude: number };
            country?: string;
            countryCode?: string;
            postalCode?: string;
            region?: string;
            regionCode?: string;
            timezone?: string;
        }

        Geo-location information associated with the profile.

        See

        GeoLocation

        • Optionalcity?: string

          City name associated with the location.

        • Optionalcontinent?: string

          Continent name associated with the location.

        • Optionalcoordinates?: { latitude: number; longitude: number }

          Geographical coordinates for the location.

          • latitude: number

            Latitude component of the coordinates.

          • longitude: number

            Longitude component of the coordinates.

        • Optionalcountry?: string

          Country name associated with the location.

        • OptionalcountryCode?: string

          Country code associated with the location.

          Remarks

          Validated to exactly COUNTRY_CODE_LENGTH characters, typically an ISO 3166-1 alpha-2 code.

        • OptionalpostalCode?: string

          Postal or ZIP code associated with the location.

        • Optionalregion?: string

          Region or state name associated with the location.

        • OptionalregionCode?: string

          Region or state code associated with the location.

        • Optionaltimezone?: string

          Time zone identifier associated with the location.

          Remarks

          Typically an IANA time zone string (e.g., "Europe/Berlin").

      • random: number

        Random value associated with the profile.

        Remarks

        Often used for deterministic bucketing (e.g., in experiments).

      • session: {
            activeSessionLength: number;
            averageSessionLength: number;
            count: number;
            id: string;
            isReturningVisitor: boolean;
            landingPage: {
                path: string;
                query: Record<string, string>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
        }

        Aggregated session statistics for the profile.

        See

        SessionStatistics

        • activeSessionLength: number

          Duration of the active session.

        • averageSessionLength: number

          Average session duration across all sessions represented by this record.

          Remarks

          The unit must match SessionStatistics.activeSessionLength.

        • count: number

          Number of sessions associated with this profile or identifier.

          Remarks

          Often used in combination with SessionStatistics.averageSessionLength.

        • id: string

          Unique identifier for this session statistics record.

        • isReturningVisitor: boolean

          Indicates whether the visitor has been seen before.

          Remarks

          true typically means the visitor has at least one prior session.

        • landingPage: {
              path: string;
              query: Record<string, string>;
              referrer: string;
              search: string;
              title?: string;
              url: string;
              [key: string]: JSONType;
          }

          Landing page for the session.

          Remarks

          Represents the first page the user visited in this session.

          See

          Page

          • path: string

            Path component of the page URL (e.g., /products/123).

          • query: Record<string, string>

            Parsed query parameters for the page.

          • referrer: string

            Referrer URL that led to the current page.

          • search: string

            Raw search string including the leading ? (e.g., "?q=test").

          • Optionaltitle?: string

            Title of the page as seen by the user.

          • url: string

            Full URL of the page.

      • stableId: string

        Stable, long-lived identifier of the profile.

        Remarks

        Intended to remain constant across sessions and devices when possible. Usually equal to id.

      • traits: Record<string, JSONType>

        Traits describing the profile (user-level attributes).

        See

        Traits

    Returns string | undefined

    A stringified primitive if found; otherwise undefined.

    Remarks

    Only string/number/boolean primitives are returned; objects/arrays are ignored.

    Example

    const value = MergeTagValueResolver.getValueFromProfile('user_email', profile)
    if (value) sendEmailTo(value)
    Copy

• normalizeSelectors: function

  • normalizeSelectors(id: string): string[]

    Generate a list of candidate selectors for a merge-tag ID.

    Parameters

    • id: string

      Merge-tag identifier (segments separated by _).

    Returns string[]

    Array of dot-path selectors to try against a profile.

    Example

    // "profile_name_first" -> [
    //   'profile',
    //   'profile.name',
    //   'profile.name.first'
    // ]
    const selectors = MergeTagValueResolver.normalizeSelectors('profile_name_first')
    Copy

• resolve: function

  • resolve(
        mergeTagEntry: MergeTagEntry | undefined,
        profile?: {
            audiences: string[];
            id: string;
            location: {
                city?: string;
                continent?: string;
                coordinates?: { latitude: number; longitude: number };
                country?: string;
                countryCode?: string;
                postalCode?: string;
                region?: string;
                regionCode?: string;
                timezone?: string;
            };
            random: number;
            session: {
                activeSessionLength: number;
                averageSessionLength: number;
                count: number;
                id: string;
                isReturningVisitor: boolean;
                landingPage: {
                    path: string;
                    query: Record<string, string>;
                    referrer: string;
                    search: string;
                    title?: string;
                    url: string;
                    [key: string]: JSONType;
                };
            };
            stableId: string;
            traits: Record<string, JSONType>;
        },
    ): string
    | undefined

    Resolve the display value for a merge-tag entry using the provided profile, falling back to the entry's configured nt_fallback when necessary.

    Parameters

    • mergeTagEntry: MergeTagEntry | undefined

      The merge-tag entry to resolve.

    • Optionalprofile: {
          audiences: string[];
          id: string;
          location: {
              city?: string;
              continent?: string;
              coordinates?: { latitude: number; longitude: number };
              country?: string;
              countryCode?: string;
              postalCode?: string;
              region?: string;
              regionCode?: string;
              timezone?: string;
          };
          random: number;
          session: {
              activeSessionLength: number;
              averageSessionLength: number;
              count: number;
              id: string;
              isReturningVisitor: boolean;
              landingPage: {
                  path: string;
                  query: Record<string, string>;
                  referrer: string;
                  search: string;
                  title?: string;
                  url: string;
                  [key: string]: JSONType;
              };
          };
          stableId: string;
          traits: Record<string, JSONType>;
      }

      Optional profile used for lookup.

      • audiences: string[]

        List of audience identifiers that this profile belongs to.

      • id: string

        Primary identifier of the profile.

      • location: {
            city?: string;
            continent?: string;
            coordinates?: { latitude: number; longitude: number };
            country?: string;
            countryCode?: string;
            postalCode?: string;
            region?: string;
            regionCode?: string;
            timezone?: string;
        }

        Geo-location information associated with the profile.

        See

        GeoLocation

        • Optionalcity?: string

          City name associated with the location.

        • Optionalcontinent?: string

          Continent name associated with the location.

        • Optionalcoordinates?: { latitude: number; longitude: number }

          Geographical coordinates for the location.

          • latitude: number

            Latitude component of the coordinates.

          • longitude: number

            Longitude component of the coordinates.

        • Optionalcountry?: string

          Country name associated with the location.

        • OptionalcountryCode?: string

          Country code associated with the location.

          Remarks

          Validated to exactly COUNTRY_CODE_LENGTH characters, typically an ISO 3166-1 alpha-2 code.

        • OptionalpostalCode?: string

          Postal or ZIP code associated with the location.

        • Optionalregion?: string

          Region or state name associated with the location.

        • OptionalregionCode?: string

          Region or state code associated with the location.

        • Optionaltimezone?: string

          Time zone identifier associated with the location.

          Remarks

          Typically an IANA time zone string (e.g., "Europe/Berlin").

      • random: number

        Random value associated with the profile.

        Remarks

        Often used for deterministic bucketing (e.g., in experiments).

      • session: {
            activeSessionLength: number;
            averageSessionLength: number;
            count: number;
            id: string;
            isReturningVisitor: boolean;
            landingPage: {
                path: string;
                query: Record<string, string>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
        }

        Aggregated session statistics for the profile.

        See

        SessionStatistics

        • activeSessionLength: number

          Duration of the active session.

        • averageSessionLength: number

          Average session duration across all sessions represented by this record.

          Remarks

          The unit must match SessionStatistics.activeSessionLength.

        • count: number

          Number of sessions associated with this profile or identifier.

          Remarks

          Often used in combination with SessionStatistics.averageSessionLength.

        • id: string

          Unique identifier for this session statistics record.

        • isReturningVisitor: boolean

          Indicates whether the visitor has been seen before.

          Remarks

          true typically means the visitor has at least one prior session.

        • landingPage: {
              path: string;
              query: Record<string, string>;
              referrer: string;
              search: string;
              title?: string;
              url: string;
              [key: string]: JSONType;
          }

          Landing page for the session.

          Remarks

          Represents the first page the user visited in this session.

          See

          Page

          • path: string

            Path component of the page URL (e.g., /products/123).

          • query: Record<string, string>

            Parsed query parameters for the page.

          • referrer: string

            Referrer URL that led to the current page.

          • search: string

            Raw search string including the leading ? (e.g., "?q=test").

          • Optionaltitle?: string

            Title of the page as seen by the user.

          • url: string

            Full URL of the page.

      • stableId: string

        Stable, long-lived identifier of the profile.

        Remarks

        Intended to remain constant across sessions and devices when possible. Usually equal to id.

      • traits: Record<string, JSONType>

        Traits describing the profile (user-level attributes).

        See

        Traits

    Returns string | undefined

    The resolved string, or undefined if the entry is invalid and no fallback is available.

    Remarks

    The resolved value depends on the current request profile, so callers must not reuse rendered output across users or requests unless the cache varies on the same profile inputs.

    Example

    const text = MergeTagValueResolver.resolve(entry, profile)
    render(text ?? 'Guest')
    Copy