In this article on my hiku series I will focus on receiving events. In my article hiku, getting started I already showed some sample code to receive events. In this article, I will dig a little deeper and explain when each event is triggered.
The hiku comes with an accompanying app. The app contains the shopping list which gets filled by scanning items with your hiku (provided the hiku recognizes the barcode). You can also add items to your shopping list in the app, by scanning or typing. All of these methods trigger an event for your webhook.
Apart from the two event types that are triggered to add something, there are also two other types of events, a battery level event and a device registered event.
Let’s look a little more in depth at the four event types, what they mean and what data you can expect in them. In the hiku, getting started article I already showed how to receive the post data (through php://input). The data you receive is json formatted. I won’t go into detail what json is, others have already done that. In PHP there is an easy function called json_decode which converts the json to an object or an associative array. What you need to know about the json you receive from hiku is that it will have a data section which contains the information you need for the four event types.
The data for each event is different. Some fields are optional while others are required. Let’s look at the data in these event types, starting with the two simple events, device registered and battery level.
A device registered event is trigger by a new user registering their hiku to your app. When you receive such an event you will get the following information:
Required/ Parameter Optional Type Description/value eventId Required Int 4 eventDesc Required String DEVICE_REGISTERED token Required HString Unique token identifying the user serialNumber Required HString hiku serial number
After this event you know you can receive more events from this user, so it makes sense to store at least the token in a database. The token will be used in other events to identify the user.
When a hiku is registered to your app using the DEVICE_REGISTERED event you will periodically get a DEVICE_BATTERY_LEVEL event. You can use this show the hiku battery level in your app. You will get the following information:
Required/ Parameter Optional Type Description/value eventId Required Int 3 eventDesc Required String DEVICE_BATTERY_LEVEL token Required HString Unique token identifying the user batteryLevel Required String Battery level, percentage from 0-100 serialNumber Required HString hiku serial number
Receiving scans from your hiku
Before I go into the two event types that are triggered by the hiku to signal a new product needs to be added to some list, let’s first look at how these events are triggered. There are basically two sources for these triggers, the hiku device and the hiku app.
With the hiku device you can either scan a code or talk to it If you scan a barcode with the hiku there are two possibilities; the barcode is recognized in the hiku database or it is not. If the hiku recognizes the barcode, it will beep to let the user know it recognized the barcode and than two things will happen. It will add the product to the shopping list in the hiku app (if the user has not changed the checkbox in the app) and it will send a PRODUCT_ENTRY event to your webhook. If the hiku does not recognize the barcode, it will send an EAN_NOT_FOUND containing the EAN it did not recognize. Besides scanning a barcode, you can also talk to the hiku to add items on the shopping list. In this case you will also get a PRODUCT_ENTRY event but instead of containing an EAN to identify the product you will get a string with the name of the product and access to the WAV file with the audio.
In the hiku app you can also add products. You can do this by selecting your favorites, which could include an EAN, or by adding items by name. In both cases you will get a PRODUCT_ENTRY event. You can also add products to the shopping list using the provided API, which will be discussed in a later article. When the API is used, a PRODUCT_ENTRY event is also generated. We will get into more detail why that is important when we cover the hiku app API.
Ok, so now let’s take a look at the two remaining events:
The PRODUCT_ENTRY event will contain the following information:
Required/ Parameter Optional Type Description/value eventId Required Int 1 eventDesc Required String PRODUCT_ENTRY token Required HString Unique token identifying the user id Required Int Shoplist entry id of the product aisle_id Required Int Aisle id for the product name Required UString Product name/description ean Required String Barcode/EAN can be NULL audioPath Required String URL to WAV file containing voice Can be empty serialNumber Optional HString hiku serial number if hiku was used
As described above, there are different scenarios which can give a PRODUCT_ENTRY event. In all cases the first 5 parameters, eventId, eventDesc, token, id and aisle_id will be filled. Even though the aisle_id is not in the documentation, so far I have always seen it.
This leaves the last 4 parameters. So far, I have seen the name always filled in with something, which is also what the documentation suggest, even for spoken products. The voice to string function they use is remarkably good. The ean parameter will be null if you speak a product to the hiku or if you type a product in the app. If you pick a product from your regulars list and that item contains the ean code, than it will show up in your PRODUCT_ENTRY event. The audioPath will be empty unless you spoke to your hiku. This leaves the parameter serialNumber which you will only get if a hiku was used. If you use the app or the API, this parameter will not be in the PRODUCT_ENTRY event.
The EAN_NOT_FOUND event is a lot simpler than the PRODUCT_ENTRY event. Let’s look at the information:
Required/ Parameter Optional Type Description/value eventId Required Int 2 eventDesc Required String EAN_NOT_FOUND token Required HString Unique token identifying the user eanNotFound Required String Unrecognized barcode
As you can see, it is rather straight forward. The user identified by token scanned a barcode with either the hiku or with the app. In the current implementation of the event you cannot tell the difference.
Putting it all together
The next step in development of your webhook is decoding the received JSON, determine what to do and after process send a response. Instead of listing it here, it makes more sense to get it from GitHub, in the directory 03 – Receiving events.
The next articles in the hiku serie:
- hiku, understanding the shopping cart
- hiku, updating the shopping cart
or read some of the previous articles in the hiku serie: