Geofencing API - Defining a standard behavior for first event

[bigludo7]

Problem description Hello Looking to define a standard behavior within our implementations. If we got a suscription for org.camaraproject.geofencing.v0.area-entered event type for a device already present in the geo zone our understanding is to not trigger an event.
Same for org.camaraproject.geofencing.v0.area-left - if the device is not in the monitored zone we do not sent notification.

If for any reason the device is not localized at the time of the subscription we apply same rule

Given the event name seems that this is the expected behavior but looking for team feedback.

Possible evolution A short description of this rule in the documentation

Alternative solution

Additional context

[alpaycetin74]

This is a safe approach, and in most cases the reasonable thing to do. Especially in "org.camaraproject.geofencing.v0.area-left" case, if you would send a notification to subscribers that are already outside the area, you would be sending it to almost all of your subscriber base. In its current definition, this subscription is to entry/exit events, not in/out statuses.

[jlurien]

Interesting question. For area-left, I have no doubts about not triggering an event if the device is outside the geofence immediately after the subscription is created. For area-entered, we are probably being coherent not triggering it either if the device is already inside the geofence when the subscription is created, but this is something to be discussed and documented.

Google Geofencing API has some logic to deal with this:

https://developer.android.com/develop/sensors-and-location/location/geofencing

Specifying INITIAL_TRIGGER_ENTER tells Location services that GEOFENCE_TRANSITION_ENTER should be triggered if the device is already inside the geofence.

In our case we may decide as an enhancement to have an additional input parameter in the subscription model, e.g. initialTriggerAreaEntered to let the client decide upon receiving or not this initial event if case when the device is already inside the geofence.

[alpaycetin74]

Yes, this can be helpful. In this case the client can register like:

... "type": "org.camaraproject.geofencing.v0.area-entered", "initialTriggerAreaEntered": true --> I'd like to know the devices who are already in the area when my subscription started ...

If the implementation cannot detect such devices for a technical reason, it can indicate lack of support by setting the parameter to false in the response, so that the client knows it will not find out about the devices that were already in the area:

... "type": "org.camaraproject.geofencing.v0.area-entered", "initialTriggerAreaEntered": false --> cannot support detection of devices already in the area ...

In the actual notifications, the same value can be used to indicate that the notification for a device that was already in the area, so that the client can differentiate:

... "type": "org.camaraproject.geofencing.v0.area-entered", "initialTriggerAreaEntered": true --> a device already in the area ...

If the notification is really for an entry event, the parameter can be omitted so that the client can differentiate. (it could also be set to false, but it is better to reduce the payload size)

... "type": "org.camaraproject.geofencing.v0.area-entered", ...

[akoshunyadi]

As discussed in today's call, the initial event may be needed also for the area_left event. E.g. when the device should be inside the area, but it has already left it, at the time of the subscription creation.

[jlurien]

As discussed in today's call, the initial event may be needed also for the area_left event. E.g. when the device should be inside the area, but it has already left it, at the time of the subscription creation.

Right, then we should consider a symmetric name for the boolean. e.g. initialTrigger

[bigludo7]

@akoshunyadi @alpaycetin74 @jlurien Try to sum-up the discussion to move forward on this.

We add an attribute initialTrigger in the request. This is a boolean. It allows requester to ask for an event if the device is already in the zone for a create (and inversely for left) at subscription time.

Do we need to have this same information in the notification? I mean have an information that this is the initial notification.

[jlurien]

Do we need to have this same information in the notification? I mean have an information that this is the initial notification.

Not sure the cost/benefit of adding this. It adds some complication to the implementation, is there any use case where this info may be useful for the client?

[nickvenezia]

The additional field would enhance measurement capabilities.

This would enable brands to directly link a location with a purchase.

A specific business use case for this functionality has already been outlined in the API Proposal for Consent and Measurement.

Get Outlook for iOShttps://aka.ms/o0ukef

---

From: Jose Luis Urien @.> Sent: Monday, February 5, 2024 11:09:58 AM To: camaraproject/DeviceLocation @.> Cc: Subscribed @.***> Subject: Re: [camaraproject/DeviceLocation] Geofencing API - Defining a standard behavior for first event (Issue #124)

Do we need to have this same information in the notification? I mean have an information that this is the initial notification.

Not sure the cost/benefit of adding this. It adds some complication to the implementation, is there any use case where this info may be useful for the client?

— Reply to this email directly, view it on GitHubhttps://github.com/camaraproject/DeviceLocation/issues/124#issuecomment-1927498124, or unsubscribehttps://github.com/notifications/unsubscribe-auth/A2QCWCMRL57CA4G7GTTY6O3YSEG6NAVCNFSM6AAAAABALWYHQ2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMRXGQ4TQMJSGQ. You are receiving this because you are subscribed to this thread.Message ID: @.***>

[bigludo7]

It adds some complication to the implementation, is there any use case where this info may be useful for the client?

I do not have on my side - Just asking the question in order to move forward on this topic.

The additional field would enhance measurement capabilities. This would enable brands to directly link a location with a purchase. A specific business use case for this functionality has already been outlined in the API Proposal for Consent and Measurement.

Thanks Nick but could you please elaborate a little bit more. Here this specific attribute is to specify that the device was in the monitored area at the subscription creation. When I look on your UC I got the feeling that the information that you target is more the event itself (link notification id to purchase).

[jlurien]

A specific business use case for this functionality has already been outlined in the API Proposal for Consent and Measurement.

Hi @nickvenezia, I have the same doubts about your comment. Could you please point to the discussion about "A specific business use case for this functionality has already been outlined in the API Proposal for Consent and Measurement."? Just for clarification, we are not questioning now the addition of initialTrigger to the request for subscription creation, but to the notification itself.

[alpaycetin74]

Hello, certainly there could be use cases where detecting the very first notification is useful. But this requires the implementation to be stateful and thread-safe, which may be more difficult to develop. The benefit vs cost should be considered. The "first notification" flag can be made optional for the implementer, and maybe they can indicate in the subscription response they are not supporting it.

[iamdatanick]

This sort of dwell time data collection could be useful for a geo-fence retargeting campaign, such as targeting all people that walked by a particular venue in the past 3 days versus those who stayed at the location for an hour.

The dwell time could be used to create a Lookalike (LAL) model to drive more people into a store based on time spent at location, then a geo-fence retargeting to follow up with people who actually went to the store with connected TV ads.

Similarly, for measurement use case this can be used to determine how many ad viewers visited a target destination (e.g., consumer sees a car dealer’s ad, what fraction are subsequently physically close to the dealer’s lot?).

Being able to compute time at a location can be used to gauge the intent of customer.

Visited car dealership three times. The third time the user spent three hours at location, because the user filled out paperwork.

[iamdatanick]

Here is a link for Meta hopefully it will help add clarity.

https://developers.facebook.com/docs/marketing-api/conversions-api/offline-events

[jlurien]

Hi @iamdatanick,

Sorry, I don't see your point regarding the dwelling info and the topic of this issue about the behaviour for the first notification after the subscription. There is a consensus to allow clients to request an initialTrigger of a notification, inmediately after the subscription is created, with the current status (in or out the geofence). After that, clients will receive a notification each time the device enters or leaves the geofence. There are no events being sent while the device remains in the geofence, but clients can deduce it from the received events.

[jlurien]

Hello, certainly there could be use cases where detecting the very first notification is useful. But this requires the implementation to be stateful and thread-safe, which may be more difficult to develop. The benefit vs cost should be considered. The "first notification" flag can be made optional for the implementer, and maybe they can indicate in the subscription response they are not supporting it.

I think that we may need the requirement for such a use case before adding more complexity to the API. For the moment I'd just include the initialTrigger indication in the request, and if we have a strong use case supporting the petition to enhance the logic in the notification, we can add it to a future version.

[nickvenezia]

The time spent at a location and frequency of a device visiting a location are ways to gauge levels on intent.

---

From: Ludovic Robert @.> Sent: Tuesday, February 6, 2024 1:58 AM To: camaraproject/DeviceLocation @.> Cc: Nick @ CENTILLION.ai @.>; Comment @.> Subject: Re: [camaraproject/DeviceLocation] Geofencing API - Defining a standard behavior for first event (Issue #124)

It adds some complication to the implementation, is there any use case where this info may be useful for the client?

I do not have on my side - Just asking the question in order to move forward on this topic.

The additional field would enhance measurement capabilities. This would enable brands to directly link a location with a purchase. A specific business use case for this functionality has already been outlined in the API Proposal for Consent and Measurement.

Thanks Nick but could you please elaborate a little bit more. Here this specific attribute is to specify that the device was in the monitored area at the subscription creation. When I look on your UC I got the feeling that the information that you target is more the event itself (link notification id to purchase).

— Reply to this email directly, view it on GitHubhttps://github.com/camaraproject/DeviceLocation/issues/124#issuecomment-1928963530, or unsubscribehttps://github.com/notifications/unsubscribe-auth/A2QCWCP3OSMMFASR4GAXXKTYSHPDVAVCNFSM6AAAAABALWYHQ2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMRYHE3DGNJTGA. You are receiving this because you commented.Message ID: @.***>

[akoshunyadi]

Just to bring back the discussion to the flag, I would propose the name 'initialEvent' because 'trigger' hasn't been used anywhere so far in the spec. It could be optional with the default value of false.

[jlurien]

Just to bring back the discussion to the flag, I would propose the name 'initialEvent' because 'trigger' hasn't been used anywhere so far in the spec. It could be optional with the default value of false.

I'm ok with the name, as long as we add in the description that this is referring to triggering an initial event immediately after the subscription creation, with the status of the device with respect to the geofence (area-entered if the device is within the geofence, or area-left if the device is outside the geofence).

[akoshunyadi]

Since this flag should be an attribute of the standard Camara event subscription, it might be better discussed in Commonalities.

[jlurien]

Since this flag should be an attribute of the standard Camara event subscription, it might be better discussed in Commonalities.

In DeviceStatus I think they have the same situation

[bigludo7]

done: https://github.com/camaraproject/Commonalities/issues/140

[alpaycetin74]

I'd like to propose to consider another detail: The initial event is triggered based on information the network already has: "Already inside" or "already outside" when subscription was created. This information may not be up-to-date, like a location information from x minutes ago, and may be misleading. I thought we could include a maxAge parameter for the initial event: If the device seems to be inside/outside the area, but this information is older than the maxAge, do not send the initial notification.

[bigludo7]

Hello @alpaycetin74 I understand the idea and the value but also I'm wondering if it complexifies not too much the API.

I tend to prefer avoiding this additional attribute and associated understanding but if the team prefers to go this way not a blocker for me.

[jlurien]

Hello @alpaycetin74 I understand the idea and the value but also I'm wondering if it complexifies not too much the API.

I tend to prefer avoiding this additional attribute and associated understanding but if the team prefers to go this way not a blocker for me.

I agree with @bigludo7. This logic can be covered using location-verification and adding too many parameters just to model the behaviour for the first event would make the API more complex to understand and use.

[alpaycetin74]

OK, I am fine with that, thank you.