Start implementing the Northfork technology

Getting started

There are a few different options to implementing the Northfork Technology. For a quick-and-easy implementation, you can utilize our powerful Widgets, where you basically need to add a few lines of code to your site to leverage the full power of the Northfork Technology. If you’d rather create your own look and feel, you can instead utilize our JS SDK or API to build whatever interface you think is right for your users.

Regardless of the approach you use, the Northfork team will always be close by and ready to support you throughout the implementation phase.

  1. Authentication

    Northfork provides an API key to be used when communicating with our services. This is sent through the X-Custom-Auth header when making requests to our API.

    curl -H 'X-Custom-Auth: {YOUR-API-KEY}'

API

This section shows a simple example of a user searching for recipes, resolving in-stock products for those recipes, and substituting a product for personal preference.

For more information, read our full API reference page here: https://developers.northfork.ai/reference

  1. Discover

    Get all recipes

    Let’s start by fetching all recipes.

    curl -X GET 'https://api.northfork.se/api/discovery/recipes' \
    -H 'X-Custom-Auth: {YOUR-API-KEY}'

    Find recipes that are “fully shopable”

    For us to only get recipes that have all ingredients currently in stock, for a specified store, we can use the store_identifier filter.

    curl -X GET 'https://api.northfork.se/api/discovery/recipes?store_identifier=100' \
    -H 'X-Custom-Auth: {YOUR-API-KEY}'

    Find vegetarian recipes

    Now, let’s add a filter for only fetching vegetarian recipes.

    curl -X GET 'https://api.northfork.se/api/discovery/recipes?store_identifier=100&diets=vegetarian' \
    -H 'X-Custom-Auth: {YOUR-API-KEY}'

    Find vegetarian recipes, with a maximum price per portion

    And with a maximum portion price.

    curl -X GET 'https://api.northfork.se/api/discovery/recipes?store_identifier=100&diets=vegetarian&max_portion_price=300' \
    -H 'X-Custom-Auth: {YOUR-API-KEY}'

SDK

Northfork provides a JS SDK to make the implementation as smooth as possible, but with the power of UI/UX in the partner’s hand. This SDK also handles cart states and store lookup, which makes utilising the full Northfork potential a breeze. Basically everything you need to build a full recipe shopping experience for your users.

  1. Installation

    Before We get into Northfork SDK you need to have NodeJS installed on your computer
    this SDK supports both browsers as well as backend services that are running on NodeJS

    After you complete the installation of NodeJS you can start installing the NF SDK inside your project directory
    https://www.npmjs.com/package/northfork-sdk – Link to the NPM registry

  2. Getting Started

    Initialising the SDK

    No need to save the response from the initialise , SKD will save and authorise user by itself after calling initialize.

    import { initialize, getRecipe } from 'northfork-sdk'
    
    // Wait until initialisation will finish
    await initialize({ username: 'my-username', stage: 'development' })
    

    Get Recipe

    To get a recipe you will have to pass the recipeID to the getRecipe method(Code example below) it will return a Promise

    note – this method excludes staples and shared ingredients

    // Get recipe by id
    const recipe = await getRecipe('recipe-id')
    
    console.log('Got recipe', recipe.title)
    

    Recipe model

    type RecipeModel = {
        id: string;
        title: string;
        products: Product[];
        portions: number;
        cookingTime: number;
        isBeingRemoved?: boolean;
    };
    

    Create Cart

    To Create a Cart you will need to pass the recipesIds to createCart method(Code example below) which will then return Promise

    // Create Cart
    const cart = await createCart(recipesIds: string[])
    
    console.log('Cart Created', cart)
    

    Cart model

    type RecipeModel = {
        id: string;
        title: string;
        products: Product[];
        portions: number;
        cookingTime: number;
        isBeingRemoved?: boolean;
    };
    
  3. Cart Actions

    Now that we have an understanding of basic SDK functions lets take a deep look at advance cart actions.
    Every CartAction returns a type CartActionResult which includes an object containing immediate cart state providing immediate update to a user and a promise with an eventual update from the API.

    type CartActionResult = {
        immeditateUpdate: CartModel;
        promise: Promise;
    };
    

    Toggle Product

    toggleProduct method can be used to include or exclude products from the cart, to use toggleProduct you will have to pass the cart object and the ID of the product that you want to include or exclude from the cart.

    toggleProduct: (cart: CartModel, productId: number) => CartActionResult;
    // Returns CartActionResult
    const updatedCart =  toggleProduct(cart, productId);
    
    console.log('Updated Cart', updatedCart.immeditateUpdate)
    
    console.log('Updated Cart from the API', await updatedCart.promise)
    

    Remove Recipe

    NF SDK supports multiple recipes when creating a cart, to remove recipes from the cart you can use removeRecipe method ,which will accept the cart object and the ID of the recipe which you wish to remove.

    removeRecipe: (cart: CartModel, recipeId: string) => CartActionResult;
    // Returns CartActionResult
    const updatedCart =  removeRecipe(cart, recipeId);
    
    console.log('Updated Cart', updatedCart.immeditateUpdate)
    
    console.log('Updated Cart from the API', await updatedCart.promise)

    Set Recipe Portions

    To change recipe portions you can use setPortions method, which accepts cart:CartModel , recipeId:string and the portions:number

    setPortions: (cart: CartModel, recipeId: string, portions: number) => CartActionResult;
    // Returns CartActionResult
    const updatedCart = setPortions(cart, recipeId, portions)
    
    console.log('Updated Cart', updatedCart.immeditateUpdate)
    
    console.log('Updated Cart from the API', await updatedCart.promise)

    Increment Product

    To increase quantity of a specific product incrementProduct method can be used.

    incrementProduct: (cart: CartModel, productId: number) => CartActionResult | undefined;
    // Returns CartActionResult
    const updatedCart = incrementProduct(cart, productId)
    
    console.log('Updated Cart', updatedCart.immeditateUpdate)
    
    console.log('Updated Cart from the API', await updatedCart.promise)

    Decrement Product

    To decrease quantity of a specific product decrementProduct method can be used.

    decrementProduct: (cart: CartModel, productId: number) => CartActionResult | undefined;
    // Returns CartActionResult
    const updatedCart = decrementProduct(cart, productId)
    
    console.log('Updated Cart', updatedCart.immeditateUpdate)
    
    console.log('Updated Cart from the API', await updatedCart.promise)

    Get Substitutes

    To get substitutes for a specific product you can use getSubstitutes method.

    Keep in mind that getSubstitutes method does not return a CartActionResult instead it will return a Promise<Product[]>

    getSubstitutes: (cart: CartModel, productId: number) => Promise<Product[]>;
    const substitutes = await getSubstitutes(cart, productId)
    
    console.log('Substitute products',substitutes)

    Swap Product

    To swap a product with one of its substitutes swapProduct method can be used.

    swapProduct: (cart: CartModel, currentProductId: number, newProduct: Product) => CartActionResult;
    // Returns CartActionResult
    const updatedCart = swapProduct(cart, productId, newProductId)
    
    console.log('Updated Cart', updatedCart.immeditateUpdate)
    
    console.log('Updated Cart from the API', await updatedCart.promise)

Web Widgets

Northfork widgets are a quick and easy way to start using the Northfork tools to enable recipe grocery shopping. The functionality is already built in with partners only required to add short javascript snippets to their web page.

 

Prerequisites

Markup for all widgets shall be placed where wanted rendered, with the exception being the Cart Widget.

 

Add Widgets library

<script id="nfw-v2" src=“https://widgets.northfork.se/dist/widgets.{user}.bundle.js”></script>

Add stylesheet

<link href=“http://widgets.northfork.se/dist/widgets.{user}.bundle.css” rel="stylesheet">
  1. Cart Widget

    Markup

    <div id=“nfw-cart-container” [data-options]></div>

    Support for multiple instantiations

    No

    Placement

    Before </body>

    Rendered

    Predetermined

    Data options

    Options may support multiple values, separated by comma. The order is nonsignificant. See the “Multi” column for reference.


  2. Meal Planner Widget

    Markup

    <div id=“nfw-menu-container” [data-options]></div>

    Support for multiple instantiations

    Yes

    Placement

    <body>

    Rendered

    Where placed

    Data options

    Options may support multiple values, separated by comma. The order is nonsignificant. See the “Multi” column for reference.

  3. Nutrition Widget

    Markup

    <div class=“nfw-anchor” data-widget=“nutrition-info” [data-options]></div>

    Support for multiple instantiations

    No

    Placement

    <body>

    Rendered

    Where placed

    Data options

    Options may support multiple values, separated by comma. The order is nonsignificant. See the “Multi” column for reference.