Satellite widget

UP Satellite integration for web based POS / Dashboard.

Satellite is an order management tool for all orders received on the UrbanPiper platform i.e. Swiggy, Zomato, UberEats, Website, etc. The widget will allow you to embed satellite and use the functionalities in your existing web based POS or dashboard.

Demo Link

Features:

  1. Order tracking (+ callback on new order) - Track orders realtime.
  2. Inventory - Stock in/out items from platforms (Swiggy, Zomato etc).
  3. Settings - Satellite and store related settings.

Read more about the features


Integration steps:

To embed satellite to your web based POS / other dashboards follow the steps:

  1. Get keys: Get APP ID and APP Secret pair for satellite web widget from UrbanPiper.
  2. Generate access token: Once you have the pair, use it to generate access token.
  3. Initialize widget: Once you have the access token, import the widget library in your website and use the token to initialize the web widget.
  4. Get widget instance: Once the widget is initialized, STL instance will be available in the global scope.

Generate access token:

Use your app_id and app_secret to generate access token. Both app_id and app_secret is sensitive information and treat this as your password.

IMPORTANT: Do not reveal this information on the client (browser) side. You are required to make the request from your server to keep it secret. Generating a token from the browser can compromise the security of your merchant’s data.

Make the following request from your server to urbanpiper server to generate access token:

Staging endpoint: https://staging.urbanpiper.com/satellite/api/v1/widgets/tokens/
Production endpoint: https://api.urbanpiper.com/satellite/api/v1/widgets/tokens/
Method: POST
Header: 'Authorization: apikey <app_id>:<app_secret>'
Body:

{
    "username": "boo", 
    "stores": [array_of_store_ids]
}

The username is the uniquely identifiable parameter for users in your system. The access token should be generated only for valid users.
stores: Optional. Should be a list of store IDs (as configured in your system), for which the given user should be able to view the orders.

In reponse you’ll get an access token which you’ll need to use to initialize the web widget.

{
    "status": "success",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InN3X2Jvb180NWl5aF83NzkyNTQxNyIsImxhc3RfbmFtZSI6IiIsImFwcCI6InNhdGVsbGl0ZSIsInJlcXVlc3RlZF9ieSI6ImJpel9hZG1fY2xpZW50c19KSFpubW9EcnZOcUciLCJhcHBfdmVyIjoiMS4wLjAiLCJiaXpfaWQiOjc3OTI1NDE3LCJzdGFmZiI6dHJ1ZSwiZmlyc3RfbmFtZSI6IiIsInVzZXJfaWQiOjM0MDIwLCJiaXpfbmFtZSI6IiBCaXJ5YW5pIDIuMFtFYXRGaXRdIiwiaml0IjoiMzQ4MTFhYTk0OTlhNGZhYWFkMzYzNTE1ZWVjZjg3NjEiLCJleHAiOjE1NzMzNzQ1NTMsImlhdCI6MTU3U1MywiYXBwX3BsdCI6IndlYi13aWRnZXQiLCJlbWFpbCI6InN0bC53aWRnZXRfYm9vKzc3OTI1NDE3QHVyYmFucGlwZXIuY29tIn0.oNNMwPFzjaASRbGBX5NE15-V1FBqB435vdAuet_YWfY"
}

In the event the server encounters an error while generating the token, status will be set to error. There would be an accompanying message indicating what went wrong.

Possible Error messages

  1. Failed to parse request payload
    Indicates that the request body has not been sent or is not a valid JSON object.
  2. You do not have sufficient permission
    The required permissions for the app_id have not been set or revoked. Check with UrbanPiper to resolve this.
  3. Missing required field
    The request body is missing out a required parameter.
  4. No matching stores found for stores values One or more store IDs have not been mapped to the stores configured in the UrbanPiper platform.

Import the widget script:

For Staging:

<script scr="https://test-stl-widget.urbanpiper.com" type="text/javanscript"></script>

For Production:

<script src="https://stl-widget.urbanpiper.com" type="text/javascript"></script>

OR Import the script asyncronously:

window.SWAsyncInit = ()=>{
    // init the widget
    // other widget code
}

(function(d){
        var js, id = 'up-webwidget', ref = d.getElementsByTagName('script')[0];
        if (d.getElementById(id)) {return;}
        js = d.createElement('script'); js.id = id; js.async = true;
        js.src = "https://stl-widget.urbanpiper.com"; // for staging use this link: https://test-stl-widget.urbanpiper.co
        js.onload = SWAsyncInit;
        ref.parentNode.insertBefore(js, ref);
}(document));

Initialize widget:

Once the above script is loaded, STL instance will be available in the global scope.

NOTE: You have to initialize it in every page wherever you want to use widget functionality. It’s recomended to put the script in the HEAD section of the page.

STL.init({
    token:'Bearer <access_token>',
    onload: ()=>{
        //         
    },
    env: <prod | staging>
});

onload will be fired once the widget is initialized.
env is optional. Default is prod


Available methods:

1. Render satellite UI:

STL.render({
    container:"HTML container ID", 
    onload:()=>{
    
    }, 
    route: "placed",
    height: "600px"
})

NOTE:

  1. onload will be fired once the satillite UI rendering is done.
  2. route - initial route to render. (Optional - dafault is placed page).
  3. height - height of the widget in px. (Optional - default is the container height).

2. Change route:

STL.route(path)

Available routes:

  1. Placed orders: placed
  2. Past orders: past-order
  3. Inventory: inventory
  4. Settings: settings

3. Realtime events:
The widget creates a secure socket connection to receive realtime events. Ex: new order, order status change. Following events are available:

  1. New order is placed in UP system - new_order
  2. Order status is changed in UP system - order_status_change

Attach a listener to the events:

STL.on(<evt name>, handler)