Interface API

interface API {
    addSegmentCodeToVisit: (segment: string) => Promise<void>;
    createRecommendationRequest: (
        flags?: { includeTagging?: boolean },
    ) => RequestBuilder;
    customer: (customer: PushedCustomer) => Promise<void>;
    defaultSession: () => Session;
    getSearchSessionParams: () => Promise<SearchSessionParams>;
    listen: <
        T extends
            (keyof LifecyleEvents)
            | (keyof PopupEvents)
            | (keyof InternalEvents),
    >(
        phase: T,
        callback: (...args: EventMapping[T]) => void,
    ) => void;
    load: () => Promise<void> | Promise<EventResponseMessage>;
    loadRecommendations: (
        element?: string | { markNostoElementClicked: string },
    ) => Promise<EventResponseMessage>;
    pageTagging: () => TaggingData;
    placements: Placements;
    recommendedProductAddedToCart: (
        productId: string,
        recoId: string,
    ) => Promise<void>;
    recordAttribution: (event: Event) => Attribution;
    recordSearch: (
        type: SearchTrackOptions,
        query: SearchQuery,
        response: SearchResult,
        options?: SearchAnalyticsOptions,
    ) => void;
    recordSearchClick: (type: SearchTrackOptions, hit: SearchHit) => void;
    recordSearchSubmit: (query: string) => void;
    removeCampaigns: (divIds: string[]) => void;
    reportAddToCart: (productId: string, recoId: string) => Promise<void>;
    resendCartContent: (cart: Cart) => Promise<void>;
    resendCartTagging: () => Promise<void>;
    resendCustomerTagging: () => Promise<void>;
    search: (
        query: SearchQuery,
        options?: SearchOptions,
    ) => Promise<SearchResult>;
    sendTagging: () => Promise<void>;
    setAutoLoad: (flag: boolean) => void;
    visit: Visits;
}

Properties

addSegmentCodeToVisit createRecommendationRequest customer defaultSession getSearchSessionParams listen load loadRecommendations pageTagging placements recommendedProductAddedToCart recordAttribution recordSearch recordSearchClick recordSearchSubmit removeCampaigns reportAddToCart resendCartContent resendCartTagging resendCustomerTagging search sendTagging setAutoLoad visit

Properties

addSegmentCodeToVisit

addSegmentCodeToVisit: (segment: string) => Promise<void>

API method to manually add a given segment code to the the current user. This is used in situations when you want to segment users based on external logic.

Sending a segment code does not automatically create the corresponding segment.

Example: to add a user to segment when they've used a discount code

nostojs(api => api.addSegmentCodeToVisit('discount code user'))

createRecommendationRequest

createRecommendationRequest: (
    flags?: { includeTagging?: boolean },
) => RequestBuilder

API method to create a recommendation request. This should only be used when you require programmatic access to the Nosto request builder.

If your site is a single-page application atop a framework such as React, Vue, Angular or the likes, and you are implementing Nosto, you must use the defaultSession method.

Type declaration

    • (flags?: { includeTagging?: boolean }): RequestBuilder

    • Parameters

      • Optionalflags: { includeTagging?: boolean }

        a set of flags to customise to request behaviour (eg. {"includeTagging":true} to initialise the request from the page tagging.

      Returns RequestBuilder

      the instance of the request.

customer

customer: (customer: PushedCustomer) => Promise<void>

API method to resend the provided customer details to Nosto. This is used in situations when the customer details is loaded after the client script initialization.

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.

If your site is a single-page application atop a framework such as React, Vue, Angular or the likes, and you are implementing Nosto using the Session API, you do not ever need this method. Nosto implementations on the single-page applications don't rely on the tagging metadata and therefore, usage of this method is indicative of an incorrect usage pattern. You should be using the Session API

Type declaration

    • (customer: PushedCustomer): Promise<void>

    • Parameters

      • customer: PushedCustomer

        the details of the currently logged in customer

      Returns Promise<void>

See

Session#setCustomer to provide the customer information.

This method is legacy method and therefore named incorrectly. Is the customer equivalent of the resendCartContent method and actually should be called resendCustomerDetails.

Example

nostojs(api => api.customer({
  first_name: "Mridang",
  last_name: "Agarwalla",
  email: "mridang@nosto.com",
  newsletter: false,
  customer_reference: "5e3d4a9c-cf58-11ea-87d0-0242ac130003"
}))

defaultSession

defaultSession: () => Session

API method to access the default session. This should only be used when implementing Nosto on a single-page application atop a framework such as React, Vue, Angular or the likes.

If you are not using a single-page application but require programmatic access to the Nosto request builder use createRecommendationRequest.

Type declaration

getSearchSessionParams

getSearchSessionParams: () => Promise<SearchSessionParams>

API method to retrieve search affinities and segments and transform it to partial search query.

Results are cached to sessionStorage and is refreshed after cacheRefreshInterval

Type declaration

Example

nostojs(api => api.getSearchSessionParams({ maxWait: 2000, cacheRefreshInterval: 60000 }).then((sessionParams) => sessionParams))

listen

listen: <
    T extends
        (keyof LifecyleEvents)
        | (keyof PopupEvents)
        | (keyof InternalEvents),
>(
    phase: T,
    callback: (...args: EventMapping[T]) => void,
) => void

API method to register a listener for JS API events. Nosto's JS API dispatches multiple events across the session lifetime.

Due to the wide gamut of events dispatched, listing them all is still a work in progress.

Example: to log a message whenever a request is made to Nosto

nostojs(api => api.listen('taggingsent'), () => console.log("The tagging was sent"));

load

load: () => Promise<void> | Promise<EventResponseMessage>

API method to load Nosto. This function is automatically invoked when the page loads.

Type declaration

Example: to manually load recommendations after DOM ready

nostojs(api => api.load());

loadRecommendations

loadRecommendations: (
    element?: string | { markNostoElementClicked: string },
) => Promise<EventResponseMessage>

API method to reload all onsite recommendations and content. This should only be used when need to reload all recommendations and content e.g. on a overlay modal.

Incorrect or extraneous usage of this method will lead to skewed page-view statistics, ad every invocation of this method results in a +1 page-view count.

Type declaration

    • (
          element?: string | { markNostoElementClicked: string },
      ): Promise<EventResponseMessage>

    • Parameters

      • Optionalelement: string | { markNostoElementClicked: string }

      Returns Promise<EventResponseMessage>

pageTagging

pageTagging: () => TaggingData

API method that to debug the state the page tagging. This is useful for debugging what Nosto sees. You are able to see all the page tagging via the debug toolbar.

If your site is a single-page application atop a framework such as React, Vue, Angular or the likes, and you are implementing Nosto using the Session API, you do not ever need this method. Nosto implementations on the single-page applications don't rely on the tagging metadata and therefore, if used, this method will always return an empty object (as there shouldn't be any tagging/metadata on the page).

This is only for debugging purposes and should never be used in a production environment

Type declaration

Example: to log the page state to the console

nostojs(api => console.log(api.pageTagging()));

placements

placements: Placements

recommendedProductAddedToCart

recommendedProductAddedToCart: (
    productId: string,
    recoId: string,
) => Promise<void>

Type declaration

    • (productId: string, recoId: string): Promise<void>

    • Parameters

      • productId: string
      • recoId: string

      Returns Promise<void>

recordAttribution

recordAttribution: (event: Event) => Attribution

Type declaration

    • (event: Event): Attribution

    • API for recording attribution without triggering an ev1 request

      Parameters

      • event: Event

        the #Event object

      Returns Attribution

recordSearch

recordSearch: (
    type: SearchTrackOptions,
    query: SearchQuery,
    response: SearchResult,
    options?: SearchAnalyticsOptions,
) => void

Record search event, should be send on any search

Type declaration

Param: type

search type

Param: query

Full API query

Param: response

{object} Full API response

recordSearchClick

recordSearchClick: (type: SearchTrackOptions, hit: SearchHit) => void

Record search click event

Type declaration

Param: type

search type

Param: hit

Full hit object from search API

recordSearchSubmit

recordSearchSubmit: (query: string) => void

Record search submit event (e.g. search form submit). Required to track organic searches.

Type declaration

    • (query: string): void

    • Record search submit event (e.g. search form submit). Required to track organic searches.

      Parameters

      • query: string

      Returns void

Param: query

Search query

removeCampaigns

removeCampaigns: (divIds: string[]) => void

Removes injected content from the supplied divIds If campaign was injected statically, then static placement just clears its contents. If dynamically, the injected element gets removed from DOM

reportAddToCart

reportAddToCart: (productId: string, recoId: string) => Promise<void>

Type declaration

    • (productId: string, recoId: string): Promise<void>

    • Parameters

      • productId: string
      • recoId: string

      Returns Promise<void>

resendCartContent

resendCartContent: (cart: Cart) => Promise<void>

API method to resend the cart content to Nosto. This is used in situations when the cart tagging is loaded after the client script initialization.

If your site is a single-page application atop a framework such as React, Vue, Angular or the likes, and you are implementing Nosto using the Session API, you do not ever need this method. Nosto implementations on the single-page applications don't rely on the tagging metadata and therefore, usage of this method is indicative of an incorrect usage pattern. You should be using the Session API

Type declaration

    • (cart: Cart): Promise<void>

    • Parameters

      • cart: Cart

        content of the cart

      Returns Promise<void>

See

Session#setCart to provide the cart information.

Example

nostojs(api => api.resendCartContent({
  items: [
    product_id: "101",
    sku_id: "101-S",
    name: "Shoe",
    unit_price: 34.99
    price_currency_code: "EUR"
  ]
}))

resendCartTagging

resendCartTagging: () => Promise<void>

API method to resend the cart tagging to Nosto. This is used in situations when the cart tagging is loaded after the client script initialization. This method reads all metadata having the class "nosto_cart" and sends the extracted cart information to Nosto.

If your site is a single-page application atop a framework such as React, Vue, Angular or the likes, and you are implementing Nosto using the Session API, you do not ever need this method. Nosto implementations on the single-page applications don't rely on the tagging metadata and therefore, usage of this method is indicative of an incorrect usage pattern. You should be using the Session API

Type declaration

    • (): Promise<void>

    • Resends the cart tagging to Nosto. Only the cart information is sent over and nothing else - no placements, no events, nothing. This method was originally used by the Magento 2 plugin. In the Magento 2 plugin the cart tagging is loaded asynchronously so a method like this was needed.

      Returns Promise<void>

See

Session#setCart to provide the cart information.

Returns

Example

nostojs(api => api.resendCartTagging())

resendCustomerTagging

resendCustomerTagging: () => Promise<void>

API method to resend the customer tagging to Nosto. This is used in situations when the customer tagging is loaded after the client script initialization. This method reads all metadata having the class "nosto_customer" and sends the extracted customer information to Nosto.

If your site is a single-page application atop a framework such as React, Vue, Angular or the likes, and you are implementing Nosto using the Session API, you do not ever need this method. Nosto implementations on the single-page applications don't rely on the tagging metadata and therefore, usage of this method is indicative of an incorrect usage pattern. You should be using the Session API

Type declaration

    • (): Promise<void>

    • Resends the customer tagging to Nosto. Only the c ustomer information is sent over and nothing else - no placements, no events, nothing. This method was originally used by the Magento 2 plugin. In the Magento 2 plugin the customer tagging is loaded asynchronously so a method like this was needed.

      Returns Promise<void>

See

Session#setCustomer to provide the customer information.

Returns

Example

nostojs(api => api.resendCustomerTagging())

search

search: (query: SearchQuery, options?: SearchOptions) => Promise<SearchResult>

Search function which requests graphql search endpoint.

Type declaration

Param: query

Search query.

Param: options

Search custom options.

Returns

Example

nostojs(api => {
 api.search({
   query: 'green',
   products: {
    fields: ['name', 'customFields.key', 'customFields.value']
   }
 })
   .then(response => response)
   .catch(err => err)
 })
})

sendTagging

sendTagging: () => Promise<void>

API method to resend all the tagging to Nosto. This is used in situations when the cart and the customer tagging is loaded after the client script initialization.

While you can use resendCartTagging and the resendCustomerTagging to achieve the same - this method will make a single request to Nosto.

If your site is a single-page application atop a framework such as React, Vue, Angular or the likes, and you are implementing Nosto using the Session API, you do not ever need this method. Nosto implementations on the single-page applications don't rely on the tagging metadata and therefore, usage of this method is indicative of an incorrect usage pattern.

Type declaration

    • (): Promise<void>

    • Resends all the tagging to Nosto. Only the page tagging is sent over and nothing else - no placements, no events, nothing. This method was originally used by the Magento 2 plugin. In the Magento 2 plugin the order tagging was loaded asynchronously so a method like this was needed.

      Returns Promise<void>

Returns

Example

nostojs(api => api.sendTagging())

setAutoLoad

setAutoLoad: (flag: boolean) => void

API method to disable the automatic initialization of Nosto. This should be used in cases when you want to manually load content.

If your site is a single-page application atop a framework such as React, Vue, Angular or the likes, and you are implementing Nosto using the Session API, you must disable auto-loading.

Type declaration

    • (flag: boolean): void

    • Parameters

      • flag: boolean

        a true or false value indicating whether to automatically load or not

      Returns void

Example

nostojs(api => api.setAutoLoad(false))
nostojs(api => api.load())

visit

visit: Visits

Settings

Member Visibility

On This Page

Properties