FD1 Client Protocol
Library Developer Home FD1 Client Protocol Home Conceptual Overview Using GET/POST Protocol Definition Authentication Authorisation Firehoses Programming Support fd1generic.js Examples General curl websocat Major APIs / Endpoints Endpoint Overview Accounts Customers Fetch Data Departments Devices Locations Products Sales SalesBuilder Session Less Common Endpoints User Interface Reserved Worked Examples Temperature Monitor Custom Report Instore Customer Display External Customer Display Cross Domain Reporting More examples Advanced Integration FieldpineDevices External Website Reseller APIs Schema Definitions custdisp.sale.* device.bluetooth.announcement device.scale.reading firehose.status sale.create sale.read Diagnostic Schema tufe.error tufe.trace tufe.status tusp.entry

fd1generic Javascript Library

fd1generic.js provides a client side Javascript library that can simplify using fd1 protocol from javascript applications. You can connect directly from browsers to Fieldpine. Customer facing applications can also use this script, but take care not to embed secrets; users should use one off tokens, and you may like to use different domains 

<HTML><BODY>
<p>My demo page</p>

<script>
    function BootPage() {
        // Called when fd1generic.js has loaded and we can initialise now
    }
</script>

<script src="fd1generic.js" onload="BootPage()"></script>
</BODY></HTML>

Once the script has loaded, your BootPage() function sets the operating environment. The script defines the global variable FieldpineFd1. The most common approach is to call FieldpineFd1.PromptLogin() 

function BootPage() {
    FieldpineFd1.PromptLogin().then(function (rslt) {
        // Called after user has entered login details
    })
}

Methods

DoLogin(Host, User, Pass, Apikey)

PromptLogin()

Displays a dialog asking the user for login details. Returns a promise that resolves after the user has entered their details. If the user clicks "ok", the method DoLogin() will automatically be called

ReceivedMessage(obj)

A function you can provide that is called for each message received. Ths receives the raw message object.

FieldpineFd1.ReceivedMessage = function(obj) {
    // ... your message handler here ...
}

SendMessage(obj)

Queues a message to send to the server. obj is a valid fd1 packet.

SendMessage_P(obj [, timeout mS ])

Queues a message to send to the server and returns a promise that is resolved when a reply is received. If no reply is received within timeout milliseconds the promise is rejected.

If your obj packet does not have a "rq" value, one will be added automatically.

FieldpineFd1.SendMessage_P(
    {
        a: "fd1.products.get_products_list",
        qo: {
            physkey: true,
            description: true,
            sku: true
        }
    }
).then(function (reply) {
    // Reply is data.rows[ { physkey: ..., description: ..., sku: ...} , ...]
})

fetch(uri, options)

Provides a fetch like access to the web socket allowing use of "fetch()" and promises rather than learning a new method, or for out of band requests that are just easier.

FieldpineFd1.fetch("/fd1/products/get_products_list",{
    body: JSON.stringify(
        { q: { pid: 123 } }
    )
})
.then(function (hreply) { return hreply.json() })
.then(function (packet) { 
    // ...packet.data has information
})

Notes

  • The URI must start /fd1/
  • The URI cannot contain any query parameters. It is blindly converted into the "a" field for Fd1
  • The body argument can be an object or a string, you do not need to JSON.stringify() as shown above
  • The function does not currently trigger any catch() handlers, but may in the future

Properties

LoginPacket

A object that is sent first when the websocket is opened. The method PromptLogin() can be used to create this object or you can manually create it. The object must confirm to the "v" portion of session.login 

FieldpineFd1.LoginPacket = {
    apikey: "My secret key"
}

IdleTimeout

The amount of seconds to consider the link inactive, and close it down. The default is a couple of minutes, but may change. The timer is not checked very often, so the actual time before closing an inactive link can be higher than this value. If set to zero, the connection is not timed out from the client.

Regardless of this IdleTimeout value, the server may impose its own idle timers and reset links.

If you open firehoses, then you should increase this value, as a firehose message will not be delivered if the link is closed. Equally you probably want to close network connectons overnight.

A connection that is idle closed will reopen automatically when you attempt to send any packets.

Flags

An array that can contain optional keywords to alter the operation. To set a flag, simply push the string FieldpineFd1.Flags.push("no-connect")

Available flags are

no-connect Do not open the socket. If already open, this does not close it. This flag can be used to completely shutdown the socket and ensure that it does not accidentally open send requests to the server again

allow-apikey Instructs the PromptLogin() function to display an entry for apikey as well as other methods.

allow-testserver Instructs the PromptLogin() function to provide a quick option to connect to a test server. Typically only used during development

Description