Import data by REST API

This tutorial covers retrieving items from your server and seamlessly integrating them into your design.

Upon the user's initiation of the design tool, an initial server request is made to retrieve the items for display. Subsequently, when the user activates the play button to open a box, a request is forwarded to your server, include the session ID from the initial item retrieval. The server then furnishes a response containing the result item.

In instances where no items are retrieved for the user, your server will respond with an empty result, accompanied by a carefully crafted message to apprise the user of the absence of available items. This approach ensures a seamless and professional user experience, underscoring the refinement of our design tool.

API Flow

Due to browser CORS policies, it's essential for requests to pass through our server initially. It's important to note that, despite this, we do not store or modify any of your data.

Api to get data

This api will call from our chanceseed server to your server and the respone data will display that data on your design

Request

Method POST

ContentType: application/json

Body: Object

Field	Type	Description
boxId	string	the box id
sessionId	string	the unique sessionId use it to map when you respone data from /result-item
enviroment	'test' or 'production'	define the enviroment of request
items	array	All current items on your design.
params	object	if it be embed on iframe. all the searchParams start with p_ on url will be add to request Sample url: https://app.chanceseed.com/b/{id}?p_user_email=youruseremail@gmailcom&p_id={userid} will be convert to an object { params : { p_user_email: '[email protected]', p_id : "userid" }}

iframe api

Response:

Response format : json

Field	Type	Description
items	array	Array of items

typescript format:

export type IBoxItem = {
  id: string;
  name: string;
  image: string;
  total: number;
  probability?: number;
  color?: string;
  textColor?: string;
};
export type GetDataBody = {
  boxId: string;
  sessionId: string;
  // items you create or add on editor
  items: IBoxItem[];
  enviroment: 'test' | 'production';
  // all the searchParams start with p_ on url sample url https://app.chanceseed.com/b/{id}?p_useremal=youruseremail@gmailcom&p_id={userid}
  params: Record<string, string>;
};

Api to get result item

After user open an box ( click an play button) we will make an request to your server. Your api server need to return an item result. You can return empty or an item with image blank to tell user they didn't win.

Request

Method POST

ContentType: application/json

Body: Object

Field	Type	Description
boxId	string	the box id
sessionId	string	the unique sessionId use it to map when you respone data from /result-item
enviroment	'test' or 'production'	define the enviroment of request
items	array	All current items on your design.
params	object	if it be embed on iframe. all the searchParams start with p_ on url will be add to request Sample url: https://app.chanceseed.com/b/{id}?p_user_email=youruseremail@gmailcom&p_id={userid} will be convert to an object { params : { p_user_email: '[email protected]', p_id : "userid" }}

Response:

Response format : json

Field	Type	Description
result	object	Result Item
items	array?	Array of items
notify	object?	It is an option if you want display a message to user. Field Type Description message string a message will display to user type toast|dialog kind of message level error|info level of message

typescript format:

export type ResultItemBody = {
  // the box id
  boxId: string;
  // current items of box
  items: IBoxItem[];
  // a unique sessionId from /api/v1/get-data
  sessionId: string;
  // all the searchParams start with p_ on url sample url https://app.chanceseed.com/b/{id}?p_useremal=youruseremail@gmailcom&p_id={userid}
  params: Record<string, string>;
};
export type ResultItemResponse={
  result?: IBoxItem; // item result
  items?: IBoxItem; // if you want update current visible items
  notify?: {
    // display a message after open item
    type: 'toast' | 'dialog';
    level: 'error' | 'info';
    message: string;
    timeout: number;
  };
}

Full code

It use hono.js but you can easy convert it to any framework or language.

import { Hono } from 'hono';
import { serve } from '@hono/node-server';
const app = new Hono();

export type IBoxItem = {
  id: string;
  name: string;
  image: string;
  total: number;
  probability?: number;
  color?: string;
  textColor?: string;
};

export type GetDataBody = {
  // the box id
  boxId: string;
  // the unique sessionId use it to map when you respone data from  /result-item
  sessionId: string;
  // items you create or add on editor
  items: IBoxItem[];
  enviroment: 'test' | 'production';
  // all the searchParams start with p_ on url sample url https://app.chanceseed.com/b/{id}?p_useremal=youruseremail@gmailcom&p_id={userid}
  params: Record<string, string>;
};
app.get('/', (ctx) => {
  return ctx.text('ok');
});
app.post('/api/v1/get-data', async (ctx) => {
  const body: GetDataBody = await ctx.req.json();
  console.info('body', body);
  // return your data it will display on your design
  return ctx.json({
    items: [
      {
        id: '263db350',
        name: 'Cool',
        image:
          'https://assets.chanceseed.com/chanceseed-assets/Smile Emoij/cool.svg',
        total: 1,
        color: '#1592e8',
        textColor: '#ffffff',
      },
      {
        id: '3db35044',
        name: 'Kiss 2',
        image:
          'https://assets.chanceseed.com/chanceseed-assets/Smile Emoij/kiss-2.svg',
        total: 1,
        color: '#fc7800',
        textColor: '#ffffff',
      },

      {
        id: 'b3504493',
        name: 'Devil',
        image:
          'https://assets.chanceseed.com/chanceseed-assets/Smile Emoij/devil.svg',
        color: '#14c187',
        total: 1,
        textColor: '#ffffff',
      },
      {
        id: '3504493a',
        name: 'In love',
        image:
          'https://assets.chanceseed.com/chanceseed-assets/Smile Emoij/in-love.svg',
        color: '#1592e8',
        total: 1,
        textColor: '#ffffff',
      },
      {
        id: '04493aaa',
        name: 'Fear',
        image:
          'https://assets.chanceseed.com/chanceseed-assets/Smile Emoij/fear.svg',
        color: '#8959a8',
        total: 1,
        textColor: '#ffffff',
      },
    ],
  });
});

export type ResultItemBody = {
  // the box id
  boxId: string;
  // current items of box
  items: IBoxItem[];
  // a unique sessionId from /api/v1/get-data
  sessionId: string;
  // all the searchParams start with p_ on url sample url https://app.chanceseed.com/b/{id}?p_useremal=youruseremail@gmailcom&p_id={userid}
  params: Record<string, string>;
};

export type ResultItemResponse = {
  result?: IBoxItem; // item result
  items?: IBoxItem; // if you want update current visible items
  notify?: {
    // display a message after open item
    type: 'toast' | 'dialog';
    level: 'error' | 'info';
    message: string;
    timeout: number;
  };
};
app.post('/api/v1/result-item', async (ctx) => {
  const body: ResultItemBody = await ctx.req.json();
  console.info('body', body);
  const response: ResultItemResponse = {
    result: body.items[0], // can return null if it don't have item
    notify: { type: 'toast', message: 'Success', level: 'info', timeout: 3000 },
  };

  return ctx.json(response);
});
serve(app);