Interface RequestBuilder

RequestBuilder is a low level API to interact with the Nosto API. It's primary purpose is to fetch recommendations and send events to the Nosto API. It is not recommended to use this API directly, but rather use the the higher level Tagging and Session APIs.

interface RequestBuilder {
    addCartCookieHash(hash: string): RequestBuilder;
    addCurrentCategories(categories: string[]): RequestBuilder;
    addCurrentCategoryIds(categoryIds: string[]): RequestBuilder;
    addCurrentCustomFields(fields: Record<string, string[]>): RequestBuilder;
    addCurrentParentCategoryIds(parentCategoryIds: string[]): RequestBuilder;
    addCurrentTags(tags: string[]): RequestBuilder;
    addCurrentVariation(variation: string): RequestBuilder;
    addCustomer(customer: PushedCustomer): RequestBuilder;
    addElements(elements: string[]): RequestBuilder;
    addOrderData(order: Order): RequestBuilder;
    disableCampaignInjection(): RequestBuilder;
    enablePreview(): RequestBuilder;
    getData(): EventRequestMessageV1;
    getEvents(): Event[];
    load(flags?: RecommendationRequestFlags): Promise<EventResponseMessage>;
    populateFrom(
        params: { data: TaggingData; forcedSegments: string[] },
        unwrappedReference?: string,
    ): RequestBuilder;
    setAffinitySignals(signals: Record<string, string[]>): RequestBuilder;
    setCartContent(cart: undefined | Cart): RequestBuilder;
    setCoupon(coupon: Coupon): RequestBuilder;
    setCurrentCategories(categories: string[]): RequestBuilder;
    setCurrentPriceFrom(value: number): RequestBuilder;
    setCurrentPriceTo(value: number): RequestBuilder;
    setCurrentTags(tags: string[]): RequestBuilder;
    setCustomer(customer: PushedCustomer): RequestBuilder;
    setElements(elements: undefined | string[]): RequestBuilder;
    setExperiments(experiments: Experiment[]): RequestBuilder;
    setMailRef(refMail: string, recRef: string): RequestBuilder;
    setPageType(pageType: undefined | PageType): RequestBuilder;
    setProducts(products: Product[], ref?: string): RequestBuilder;
    setRecommendationRef(recRef: string, recRefSrc?: string): RequestBuilder;
    setRefs(refs: Record<string, string>): RequestBuilder;
    setResponseMode(mode: RenderMode): RequestBuilder;
    setRestoreLink(restoreLink: undefined | string): RequestBuilder;
    setSegmentCodes(segments: string[]): RequestBuilder;
}

Methods

addCartCookieHash addCurrentCategories addCurrentCategoryIds addCurrentCustomFields addCurrentParentCategoryIds addCurrentTags addCurrentVariation addCustomer addElements addOrderData disableCampaignInjection enablePreview getData getEvents load populateFrom setAffinitySignals setCartContent setCoupon setCurrentCategories setCurrentPriceFrom setCurrentPriceTo setCurrentTags setCustomer setElements setExperiments setMailRef setPageType setProducts setRecommendationRef setRefs setResponseMode setRestoreLink setSegmentCodes

Methods

addCartCookieHash

  • addCartCookieHash(hash: string): RequestBuilder

  • Sets the hash of the current cart cookie for ensure that the cart tagging isn't cached. In most cases, simply reading the customer's 2c.cid cookie and generating a SHA256 checksum will suffice.

    Parameters

    • hash: string

    Returns RequestBuilder

    Deprecated

addCurrentCategories

  • addCurrentCategories(categories: string[]): RequestBuilder

  • Adds the given category names to the request. Any category name specified here are simply added to the request as personalisation filtering hints.

    Parameters

    • categories: string[]

      the array of category ids

    Returns RequestBuilder

addCurrentCategoryIds

  • addCurrentCategoryIds(categoryIds: string[]): RequestBuilder

  • Adds the given category ids to the request. Any category ids specified here are simply added to the request as personalisation filtering hints.

    Parameters

    • categoryIds: string[]

      the array of category ids

    Returns RequestBuilder

addCurrentCustomFields

  • addCurrentCustomFields(fields: Record<string, string[]>): RequestBuilder

  • Adds the given current custom fields to the request. Any custom fields specified here are simply added to the request as personalisation filtering hints.

    Parameters

    • fields: Record<string, string[]>

      custom field key-value pairs

    Returns RequestBuilder

addCurrentParentCategoryIds

  • addCurrentParentCategoryIds(parentCategoryIds: string[]): RequestBuilder

  • Adds the given parent category ids to the request. Any parent category ids specified here are simply added to the request as personalisation filtering hints.

    Parameters

    • parentCategoryIds: string[]

    Returns RequestBuilder

addCurrentTags

  • addCurrentTags(tags: string[]): RequestBuilder

  • Adds the given current tags to the request. Any tags (tags1, tags12, or tags13) specified here are simply added to the request as personalisation filtering hints.

    Parameters

    • tags: string[]

      the array of tags

    Returns RequestBuilder

addCurrentVariation

  • addCurrentVariation(variation: string): RequestBuilder

  • Sets the current variation identifier for the session. A variation identifier identifies the current currency (or the current customer group). If your site uses multi-currency, you must provide the ISO code current currency being viewed.

    It is not recommended to pass the variation identifier to an request builder but instead leverage the tagging.

    Parameters

    • variation: string

      the case-sensitive identifier of the current variation

    Returns RequestBuilder

addCustomer

  • addCustomer(customer: PushedCustomer): RequestBuilder

  • Sets the information about the currently logged in customer. If the current customer is not provided, you will not be able to leverage features such as triggered emails. While it is recommended to always provide the details of the currently logged in customer, it may be omitted if there are concerns about privacy or compliance.

    It is not recommended to pass the current customer details to the request builder but rather use the customer tagging.

    Parameters

    Returns RequestBuilder

addElements

  • addElements(elements: string[]): RequestBuilder

  • Adds the given elements (or placements) to the request. Any identifiers specified here are simply added to the elements already in the request.

    Parameters

    • elements: string[]

      the array of placements

    Returns RequestBuilder

    Example: To load data for a single placement

    nostojs(api => api
      .createRecommendationRequest()
      .addElements(['bestseller-home'])
      .loadRecommendations());

addOrderData

disableCampaignInjection

enablePreview

  • enablePreview(): RequestBuilder

  • Enables the preview mode for the current request. The preview mode is automatically gathered from the current context's preview mode. If the debug toolbar is showing and preview mode is enabled, there is no need to invoke this function.

    Returns RequestBuilder

getData

getEvents

load

populateFrom

setAffinitySignals

setCartContent

  • setCartContent(cart: undefined | Cart): RequestBuilder

  • Adds the cart object to the current request. This should be preferably on every page load so as to keep the cart state as fresh as possible.

    Parameters

    • cart: undefined | Cart

      the details of the current shopping basket

    Returns RequestBuilder

setCoupon

setCurrentCategories

  • setCurrentCategories(categories: string[]): RequestBuilder

  • Sets the given category names to the request. Any category names specified here override the category names in the request.

    Parameters

    • categories: string[]

      the array of category ids

    Returns RequestBuilder

setCurrentPriceFrom

  • setCurrentPriceFrom(value: number): RequestBuilder

  • Sets the current lower price range to the request. Faceting needs to be enabled for the slot in order for this to function. Any lower value specified here are simply added to the request as personalisation filtering hints.

    Parameters

    • value: number

      the lower range of the price

    Returns RequestBuilder

setCurrentPriceTo

  • setCurrentPriceTo(value: number): RequestBuilder

  • Sets the current upper price range to the request. Faceting needs to be enabled for the slot in order for this to function. Any upper value specified here are simply added to the request as personalisation filtering hints.

    Parameters

    • value: number

      the upper range of the price

    Returns RequestBuilder

setCurrentTags

  • setCurrentTags(tags: string[]): RequestBuilder

  • Sets the given current tags to the request. Any tags (tags1, tags12, or tags13) specified here are simply set to the request as personalisation filtering hints.

    Parameters

    • tags: string[]

      the array of tags

    Returns RequestBuilder

setCustomer

  • setCustomer(customer: PushedCustomer): RequestBuilder

  • Sets the information about the currently logged in customer. If the current customer is not provided, you will not be able to leverage features such as triggered emails. While it is recommended to always provide the details of the currently logged in customer, it may be omitted if there are concerns about privacy or compliance.

    It is not recommended to pass the current customer details to the request builder but rather use the customer tagging.

    Parameters

    • customer: PushedCustomer

      the details of the currently logged in customer

    Returns RequestBuilder

setElements

  • setElements(elements: undefined | string[]): RequestBuilder

  • Sets the given elements (or placements) to the request. Any identifiers specified here override all elements already in the request.

    Parameters

    • elements: undefined | string[]

      the array of placements

    Returns RequestBuilder

    Example: To load data for a single placement

    nostojs(api => api
      .createRecommendationRequest()
      .setElements(['bestseller-home'])
      .loadRecommendations());

setExperiments

setMailRef

setPageType

  • setPageType(pageType: undefined | PageType): RequestBuilder

  • Sets the identifier of the current page type to the current request. The different page types are product, front, search, cart, order, category, notfound and other.

    Parameters

    • pageType: undefined | PageType

      the current page type

    Returns RequestBuilder

setProducts

setRecommendationRef

setRefs

setResponseMode

  • setResponseMode(mode: RenderMode): RequestBuilder

  • Sets the response mode for the current request. The response mode can be used to switch between HTML and JSON. Here is an exhaustive list of the response modes.

    Modes Description
    HTML HTML (SSR)
    JSON_170x170 Raw JSON with 170x170px original aspect images
    JSON_100_X_100 Raw JSON with 100x100px original aspect images
    JSON_90x70 Raw JSON with 90x70px original aspect images
    JSON_50x50 Raw JSON with 50x50px original aspect images
    JSON_30x30 Raw JSON with 30x30px original aspect images
    JSON_100x140 Raw JSON with 100x140px original aspect images
    JSON_200x200 Raw JSON with 200x200px original aspect images
    JSON_400x400 Raw JSON with 400x400px original aspect images
    JSON_750x750 Raw JSON with 750x750px original aspect images
    JSON_10_MAX_SQUARE Raw JSON with 100x100px center squared images
    JSON_200x200_SQUARE Raw JSON with 200x200px center squared images
    JSON_400x400_SQUARE Raw JSON with 400x400px center squared images
    JSON_750x750_SQUARE Raw JSON with 750x750px center squared images
    JSON_ORIGINAL Raw JSON with the original untouched images

    Parameters

    Returns RequestBuilder

setRestoreLink

  • setRestoreLink(restoreLink: undefined | string): RequestBuilder

  • Sets the restore link for the current session. Restore links can be leveraged in email campaigns. Restore links allow the the user to restore the cart contents in a single click.

    Read more about to leverage the restore cart link

    It is not recommended to pass the current restore link to the request builder but rather use the tagging approach.

    Parameters

    • restoreLink: undefined | string

    Returns RequestBuilder

setSegmentCodes

  • setSegmentCodes(segments: string[]): RequestBuilder

  • Sets the given list of manual segment identifiers to the current request. This method allows you explicitly associate the current customer with a segment.

    Parameters

    • segments: string[]

      the list of force segment identifiers

    Returns RequestBuilder

Settings

Member Visibility

On This Page

Methods