Quick Start

Userize lets you easily trigger actions in your application based on natural language prompts. It consists of three parts:

• Platform: Allows you to configure your project’s preferences. You can visit it here.
• API: Transforms your user’s query into a cascade of actions.
• JavaScript Client: Abstracts the API complexity, letting you set up your actions in just a few lines of code. You’ll discover more about it in this guide.

Following these steps, you’ll be able to run your first AI-triggered action in minutes.

Step 1: Set up your Project

To get started, visit the Userize platform and either log in or create a new account.

Create a new project

Once you’re logged in, you can create a New Project. Click on the button and choose:

• Project’s Name and Description: This information helps you and your team easily identify the project.
• Invite Members: You can immediately invite people to collaborate on the project, or you can do it at a later stage.

Get your API key

In the Project Settings page, you can generate your unique API key.

Ensure you copy and securely store the key: it will authenticate your API requests.

Step 2: Configure the Actions

Let’s suppose you are building an e-commerce. For simplicity, the user can only perform two actions: search for an item, and select an item to buy. These two actions can either run independently, or sequentially.

Here are our possible flows:

Our API will select the best flow, with the appropriate parameters, for you. All you need to do is choose your actions.

From your project’s dashboard, navigate to the Actions configuration page and follow the steps.

Write an Actions Overview

In the Actions configuration page, you have the possibility to describe what your actions will be used for. The API will work fine even without it, but you can get more accurate results by describing your final goal.

Copy and paste the following description:

User is navigating through an e-commerce, which displays several items. User can search for a subset of items, and select one to add to the cart. If requested by the user, the e-commerce site can automatically add the best match from the search results directly to the cart.

Customize an Action

You may deeply customize an action to ensure the behavior matches your expectations. Let’s see how to do it by examples.

Example: search action

Click on the New action button to create a new action.

Update the action configuration as follows:

1. Click on action name, and update it to search.
2. Click on the action description, and introduce what the action does:

   Enables users to search for an item using specified search parameters.

3. Add a parameter and call it color.
   • Describe what the parameter does:

     It allows user to search for items matching a desired color.

   • Leave other fields as they are.
4. Save the action.

Example: select action

Let’s repeat the steps for the select action:

1. Create a new action, rename it to select, and add description:

   Given a set of items, adds one to the cart based on the selection criteria.

2. Add a parameter and rename it to choose_item.
   • Describe the parameter:

     Item selection criteria. If not provided, use “newest”.

   • Set the parameter as optional.
   • Force the parameter to a set of specific values: newest, cheapest, trendy
3. Save the action.

Step 3: Add Userize to your App

Install userize-js

First, install userize-js using your preferred package manager:

npm install userize-js

yarn add userize-js

pnpm add userize-js

Add your API key

If you have stored your API key in the environment variable USERIZE_API_KEY, you can safely skip this step.

Otherwise, you can explicitly set the API key in your code:

import { initClient } from 'userize-js';
 
...
 
initClient('YOUR-API-KEY')

Register the actions

It’s coding time! Let us write our actions.

function search(cascade, color) {
  // Assume a list of "items"
 
  const filteredItems = items.filter((item) => item.color === color);
 
  // Optionally, we can run different flows
  // if one of these items will be add to cart or not
  if (cascade.event.next !== null) {
    // Next action will just consume filtered items
    return filteredItems;
  } else {
    // Here we may show filtered items to user
    console.log('Filtered Items: ', filteredItems);
  }
}
 
function select(cascade, chooseItem) {
  // We can retrieve items from the "search" action
  const filteredItems = cascade.data ?? items;
 
  let selectedItem;
 
  switch (chooseItem) {
    case 'newest':
      selectedItem = filteredItems.sort((a, b) => b.addedAt.getTime() - a.addedAt.getTime())[0];
      break;
 
    case 'cheapest':
      selectedItem = filteredItems.sort((a, b) => a.price - b.price)[0];
      break;
 
    case 'trendy':
      selectedItem = filteredItems.sort((a, b) => b.lastBoughtAt.getTime() - a.lastBoughtAt.getTime())[0];
      break;
  }
 
  // We may now addToCart(selectedItem)
  console.log('Selected Item: ', selectedItem);
}

import type { UserizeActionCascade } from 'userize-js';
 
function search(cascade: UserizeActionCascade, color: string) {
  // Assume a list of "items"
 
  const filteredItems = items.filter((item) => item.color === color);
 
  // Optionally, we can run different flows
  // if one of these items will be add to chart or not
  if (cascade.event.next !== null) {
    // Next action will just consume filtered items
    return filteredItems;
  } else {
    // Here we may show filtered items to user
    console.log('Filtered Items: ', filteredItems);
  }
}
 
function select(cascade: UserizeActionCascade, chooseItem: string | undefined) {
  // We can retrieve items from the "search" action
  const filteredItems = (cascade.data as typeof items | undefined) ?? items;
 
  let selectedItem;
 
  switch (chooseItem) {
    case 'newest':
      selectedItem = filteredItems.sort((a, b) => b.addedAt.getTime() - a.addedAt.getTime())[0];
      break;
 
    case 'cheapest':
      selectedItem = filteredItems.sort((a, b) => a.price - b.price)[0];
      break;
 
    case 'trendy':
      selectedItem = filteredItems.sort((a, b) => b.lastBoughtAt.getTime() - a.lastBoughtAt.getTime())[0];
      break;
  }
 
  // We may now addToCart(selectedItem)
  console.log('Selected Item: ', selectedItem);
}

Finally, we can register our actions, making them ready to be triggered by the API.

import { initClient, registerAction } from 'userize-js';
import { search, select } from 'actions';
 
...
 
initClient('YOUR-API-KEY')
 
registerAction('search', search);
registerAction('select', select);

Step 4: Test it

Let’s prepare some sample data for testing.

export const items = [
  {
    name: "jeans",
    color: "blue",
    price: 20,
    addedAt: new Date("2024-08-12"),
    lastBoughtAt: new Date("2024-10-02"),
  },
  {
    name: "tshirt",
    color: "red",
    price: 5,
    addedAt: new Date("2024-09-02"),
    lastBoughtAt: new Date("2024-10-05"),
  },
  {
    name: "dress",
    color: "black",
    price: 15,
    addedAt: new Date("2024-08-15"),
    lastBoughtAt: new Date("2024-10-01"),
  },
  {
    name: "pants",
    color: "blue",
    price: 10,
    addedAt: new Date("2024-07-29"),
    lastBoughtAt: new Date("2024-09-24"),
  },
];

import { items } from "data";
 
function search(cascade, color) {
  ...
}
 
function select(cascade, chooseItem) {
  ...
}

Trigger Actions Cascade

To initiate the Actions Cascade, simply pass a user’s request to triggerActions:

import { initClient, registerAction, triggerActions } from 'userize-js';
import { search, select } from 'actions';
 
...
 
initClient('YOUR-API-KEY')
 
registerAction('search', search);
registerAction('select', select);
 
...
 
triggerActions("I love black, show me something cool")
/**
 *
 * Actions run: `search`
 *
 * It should display, from console:
 *
 * Filtered Items: [{
 *   addedAt: Thu Aug 15 2024 00:00:00,
 *   color: "black",
 *   lastBoughtAt: Tue Oct 01 2024 00:00:00,
 *   name: "dress",
 *   price: 15,
 * },
 * {
 *   addedAt: Sat Aug 10 2024 00:00:00,
 *   color: "black",
 *   lastBoughtAt: Tue Oct 08 2024 00:00:00,
 *   name: "socks",
 *   price: 2,
 * }]
 */
 
triggerActions("I want to buy the very latest dress for the party")
/**
 *
 * Actions run: `select`
 *
 * It should display, from console:
 *
 * Selected Item: {
 *   addedAt: Mon Sep 02 2024 00:00:00,
 *   color: "red",
 *   lastBoughtAt: Sat Oct 05 2024 00:00:00,
 *   name: "tshirt",
 *   price: 5,
 * }
 */
 
triggerActions("I don't care what to buy, I just need it to be blue and cheap")
/**
 *
 * Actions run: `search` -> `select`
 *
 * It should display, from console:
 *
 * Selected Item: {
 *   addedAt: Mon Jul 29 2024 02:00:00,
 *   color: "blue",
 *   lastBoughtAt: Tue Sep 24 2024 00:00:00,
 *   name: "pants",
 *   price: 10,
 * }
 */

🎉 Congratulations!

You’ve successfully built and tested your first AI-powered action cascade with Userize! 🚀

Next Steps

1. Customize Actions for Your Project: Tailor actions to suit your specific project needs and workflows.
2. Explore Advanced Topics: Dive into advanced features to achieve more accurate results, enhance your project’s security, and build more complex action cascades.
3. Collaborate: Share your feedback and contribute to the project by reporting issues or suggesting improvements.