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>;
        },
    ): undefined
    | string

    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 currently 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 should 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 undefined | string

    A stringified primitive if found; otherwise undefined.

    Example

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

    Remarks

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

• isMergeTagEntry: function

  • isMergeTagEntry(
        embeddedEntryNodeTarget: unknown,
    ): embeddedEntryNodeTarget is {
        fields: {
            nt_fallback?: string;
            nt_mergetag_id: string;
            nt_name: string;
        };
        metadata: {
            tags: { sys: { id: string; linkType: "Tag"; type: "Link" } }[];
            [key: string]: JSONType;
        };
        sys: {
            contentType: {
                sys: { id: "nt_mergetag"; linkType: "ContentType"; type: "Link" };
            };
            createdAt: any;
            environment: {
                sys: { id: string; linkType: "Environment"; type: "Link" };
            };
            id: string;
            locale?: string;
            publishedVersion: number;
            revision: number;
            space: { sys: { id: string; linkType: "Space"; type: "Link" } };
            type: "Entry";
            updatedAt: any;
        };
    }

    Type guard to ensure the input is a MergeTagEntry.

    Parameters

    • embeddedEntryNodeTarget: unknown

      Unknown value to validate.

    Returns embeddedEntryNodeTarget is {
        fields: {
            nt_fallback?: string;
            nt_mergetag_id: string;
            nt_name: string;
        };
        metadata: {
            tags: { sys: { id: string; linkType: "Tag"; type: "Link" } }[];
            [key: string]: JSONType;
        };
        sys: {
            contentType: {
                sys: { id: "nt_mergetag"; linkType: "ContentType"; type: "Link" };
            };
            createdAt: any;
            environment: {
                sys: { id: string; linkType: "Environment"; type: "Link" };
            };
            id: string;
            locale?: string;
            publishedVersion: number;
            revision: number;
            space: { sys: { id: string; linkType: "Space"; type: "Link" } };
            type: "Entry";
            updatedAt: any;
        };
    }

    true if the input is a valid merge-tag entry.

    Example

    if (MergeTagValueResolver.isMergeTagEntry(node)) {
      // safe to read fields
    }
    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:
            | undefined
            | {
                fields: {
                    nt_fallback?: string;
                    nt_mergetag_id: string;
                    nt_name: string;
                };
                metadata: {
                    tags: { sys: { id: string; linkType: "Tag"; type: "Link" } }[];
                    [key: string]: JSONType;
                };
                sys: {
                    contentType: {
                        sys: { id: "nt_mergetag"; linkType: "ContentType"; type: "Link" };
                    };
                    createdAt: any;
                    environment: {
                        sys: { id: string; linkType: "Environment"; type: "Link" };
                    };
                    id: string;
                    locale?: string;
                    publishedVersion: number;
                    revision: number;
                    space: { sys: { id: string; linkType: "Space"; type: "Link" } };
                    type: "Entry";
                    updatedAt: any;
                };
            },
        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>;
        },
    ): undefined
    | string

    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:
          | undefined
          | {
              fields: {
                  nt_fallback?: string;
                  nt_mergetag_id: string;
                  nt_name: string;
              };
              metadata: {
                  tags: { sys: { id: string; linkType: "Tag"; type: "Link" } }[];
                  [key: string]: JSONType;
              };
              sys: {
                  contentType: {
                      sys: { id: "nt_mergetag"; linkType: "ContentType"; type: "Link" };
                  };
                  createdAt: any;
                  environment: {
                      sys: { id: string; linkType: "Environment"; type: "Link" };
                  };
                  id: string;
                  locale?: string;
                  publishedVersion: number;
                  revision: number;
                  space: { sys: { id: string; linkType: "Space"; type: "Link" } };
                  type: "Entry";
                  updatedAt: any;
              };
          }

      The merge-tag entry to resolve.

      • undefined
      • {
            fields: {
                nt_fallback?: string;
                nt_mergetag_id: string;
                nt_name: string;
            };
            metadata: {
                tags: { sys: { id: string; linkType: "Tag"; type: "Link" } }[];
                [key: string]: JSONType;
            };
            sys: {
                contentType: {
                    sys: { id: "nt_mergetag"; linkType: "ContentType"; type: "Link" };
                };
                createdAt: any;
                environment: {
                    sys: { id: string; linkType: "Environment"; type: "Link" };
                };
                id: string;
                locale?: string;
                publishedVersion: number;
                revision: number;
                space: { sys: { id: string; linkType: "Space"; type: "Link" } };
                type: "Entry";
                updatedAt: any;
            };
        }

        • fields: { nt_fallback?: string; nt_mergetag_id: string; nt_name: string }

          • Optionalnt_fallback?: string

            Fallback value to use when the merge tag cannot be resolved.

          • nt_mergetag_id: string

            Internal identifier of the merge tag.

          • nt_name: string

            Human-readable name of the merge tag.

        • metadata: {
              tags: { sys: { id: string; linkType: "Tag"; type: "Link" } }[];
              [key: string]: JSONType;
          }

          Contentful metadata, including tags.

        • sys: {
              contentType: {
                  sys: { id: "nt_mergetag"; linkType: "ContentType"; type: "Link" };
              };
              createdAt: any;
              environment: { sys: { id: string; linkType: "Environment"; type: "Link" } };
              id: string;
              locale?: string;
              publishedVersion: number;
              revision: number;
              space: { sys: { id: string; linkType: "Space"; type: "Link" } };
              type: "Entry";
              updatedAt: any;
          }

          System fields extended to constrain the content type to nt_mergetag.
    • 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 currently 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 should 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 undefined | string

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

    Example

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