Region Event Callbacks

Introduction

Colocator can be configured to send region entries, exits and dwells to a single URL as a post. Please contact Crowd Connected to enable this functionality on your app key.

Events are fired when any device enters or exits any region. For devices that dwell in a region, events are fired periodically with increasing dwell values.

From the point that callbacks are configured, region creation, update and deletion events are also sent, to a different URL.

There is limited retry functionality built in to the API calls and a limited queue capacity. If your server is slow to respond or refuses API calls data will be dropped.

Segment Query Callbacks can also be used to send events to external systems. They enable complex logic to be performed within Colocator, avoiding the need to store and query the entire history of region events client-side. A segment combines multiple filters based on current location, and also location history. As devices meet the segment filter rules, callbacks are sent in real-time.

Region Events

• Every Region that is created will send these events automatically.
• Every 30* seconds all region actions that occurred in the past 30* seconds will be sent.
• Each payload can include up to 100* region actions, multiple batches will be sent if necessary.
• At peak times we expect the number of region actions to be 100 per second, though this is very client specific.
• Exit region actions will include a dwell time, if available. (In very rare cases it will be missing. It will only happen if the callback process is initiated mid-event)
• Every 5* minutes a dwell time will be sent for every device that is currently in a region.

* Subject to change

Region Event Payload

{  
   "regionActions":[  
      {  
         "deviceId":"e8734a97-443b-4b84-9dbe-852bb94ffbfc",
         "aliasId":"ALIAS_ID",
         "regionId":"84521fc3-cd21-42d9-aaca-2fee9eb3be26",
         "regionActionType":"ENTRY",
         "timestamp":1552910243412,
         "application":"APP_KEY",
         "authKey":"AUTH_KEY"
      },
      {  
         "deviceId":"e8734a97-443b-4b84-9dbe-852bb94ffbfc",
         "aliasId":"ALIAS_ID",
         "regionId":"84521fc3-cd21-42d9-aaca-2fee9eb3be26",
         "regionActionType":"EXIT",
         "dwell":"2046523",
         "timestamp":1552910245630,
         "application":"APP_KEY",
         "authKey":"AUTH_KEY"
      },
      {  
         "deviceId":"e8734a97-443b-4b84-9dbe-852bb94ffbfc",
         "aliasId":"ALIAS_ID",
         "regionId":"84521fc3-cd21-42d9-aaca-2fee9eb3be26",
         "regionActionType":"DWELL",
         "dwell":"301265",
         "timestamp":1552910245625,
         "application":"APP_KEY",
         "authKey":"AUTH_KEY"
      }
   ]
}

Region Event Fields

Region Updates

Region Creates, Updates and Deletions will be sent to a different single URL as a POST.

If regions are created before the simple callback system is set up then the creation event will not be sent. To get the initial set of regions or to do a full refresh use the Regions API.

Region Update Payload

{  
   "newRegion":{  
      "id":"e1e11ef3-ccc4-4c52-a497-22d73bbc74cb",
      "name":"Test A",
      "areaType":"Stage",
      "sufaceId":"52b7d7fe-28c2-4629-8211-87dc23096b67",
      "latLngAlt":[  
         [  
            51.24663195429334,
            -0.5966091156005859,
            0
         ],
         [  
            51.246605090596844,
            -0.5826616287231446,
            0
         ],
         [  
            51.240318554170045,
            -0.5820608139038087,
            0
         ],
         [  
            51.24034542153845,
            -0.596909523010254,
            0
         ],
         [  
            51.24663195429334,
            -0.5966091156005859,
            0
         ]
      ]
   },
   "oldReigon":{  
      "id":"e1e11ef3-ccc4-4c52-a497-22d73bbc74cb",
      "name":"Test B",
      "areaType":"Other",
      "sufaceId":"52b7d7fe-28c2-4629-8211-87dc23096b67",
      "latLngAlt":[  
         [  
            51.24663195429334,
            -0.5966091156005859,
            0
         ],
         [  
            51.246605090596844,
            -0.5826616287231446,
            0
         ],
         [  
            51.240318554170045,
            -0.5820608139038087,
            0
         ],
         [  
            51.24034542153845,
            -0.596909523010254,
            0
         ],
         [  
            51.24663195429334,
            -0.5966091156005859,
            0
         ]
      ]
   },
   "application":"APP_KEY",
   "authKey":"AUTH_KEY"
}

Region Update Fields