GeoDistance MatchedPoints in Response

[karnowski]

Background

Adzerk has a popular private beta feature called GeoDistance Targeting where individual ads will only serve if the viewer's precise location is within a given range of a specific latitude/longitude. For example, say Dunkin Donuts wanted to show a coupon only if the viewer was within 5km of a Dunkin Donuts location. This ad campaign might know the location of hundreds of donut shops in a region.

This feature is growing in popularity, especially with mobile clients, and we are preparing for when it will become generally available to all Adzerk customers. The Android & iOS SDKs are already working towards passing the precise location needed by adding extra request parameters. However, there is an additional feature that we don't currently support -- getting the list of "matched points" on the response.

Concept: Matched Points

There are really two main use cases for GeoDistance Targeting -- hyperlocal ads and map-based user interfaces. For hyperlocal ads, we just return the correct ad when the viewer is close enough to one of the ad's desired locations. All we have to do there is pass extra location information on the request, and the extra request parameters allow us to do that (via intendedLatitude and intendedLongitude values).

For map-based UIs, though, the integrating developer is showing the viewer a map with all the responding ads as highlighted map points. To do that, when requesting ads, you also ask for the matched map points. The integrating developer does this by including includeMatchedPoints=true on the request. Again, the extra request params already cover this. However, in the response, we will include an array of matchedPoints that give the latitude/longitude for each returned ad. This gives the integrating developer a way to display each decision as "promoted map pins" on their map.

Acceptance Criteria

• For each decision in the response, if present, the matchedPoints values should be available to the integrating developer.
• matchedPoints live on the decision as a sibling of contents, impressionUrl, events, and others.
• matchedPoints is an array of JSON objects that include the following values:
  • lat: a string containing a latitude value, for example "38.889811"
  • lon: a string containing a longitude value, for example "-78.93315"

[karnowski]

Update, note I had incorrectly had long as the longitude value in matchedPoints, it's actually lon with no "g". 🤷‍♂️ I've updated the comment above.

[subdigital]

Do you want me to convert this string to a Double? This would make it easier for an integrating developer to utilize CoreLocation's CLLocationCoordinate2D data type, which is essential for working with geo points on a map, etc.

[karnowski]

@subdigital Actually @bdiegel went ahead and converted these to the native Android geolocation objects. Would that be appropriate here too? Just returning it as a CLLocationCoordinate2D object?

[subdigital]

I can do this, but I'm not sure if it's worth linking with CoreLocation (which in my experience can sometimes flag apps for additional scrutiny on submission if they don't use location otherwise).

It's probably fine to do so, but also easy for a developer to convert from a struct we create...

[karnowski]

Ah, that's a really good point. How about if we we just include an example snippet in the README? We definitely don't want apps flagged because of our SDK. Thanks!