What is Context? on

What is Context?

Context describes the state of the user and the screen that they are interacting with in a structured way, telling Button what a user is interacting with. From this Context, Button infers what the user wants to do next, and can provide the relevant Button to match that intent.

You can find the CocoaDocs for Context here.


How do I define context?

Context is defined by setting Context fields on a Context object, and assigning values to properties on each Context field. There are several different types of Context fields, each with their own unique properties. Here, we outline the different Context fields, and the properties they can take.

Remember: All Context fields are optional. Pass as little or as much Context as you have; the more you pass, the more likely Button will be able to find a contextually relevant action for the user.

Location Context

The Location Context fields provides information about a place, location, venue or POI. Button Context supports two different Location fields for you to specify, allowing additional detail:

  • userLocation: The user's current location. Usually expressed as latitude & longitude.
  • subjectLocation: A location that the user is looking at or interested in. This can be expressed as latitude and longitude, but also by name, address or with partner-specific identifiers.

Below is some sample code for setting the User & Subject Location Context fields to a Context object.

/** User Location **/
// Create a User Location Context Field
let userLocation = BTNLocation(latitude: <#latitude#>, longitude: <#longitude#>)

// Set the User Location Context Field to a Context object
let context = BTNContext(userLocation: userLocation)
/** User Location **/
// Create a User Location Context Field
BTNLocation *userLocation = [BTNLocation locationWithLatitude:<#latitude#> longitude:<#longitude#>];

// Set the User Location Context Field to a Context object
BTNContext *context = [BTNContext contextWithUserLocation:userLocation];
/** Subject Location **/
// Create a Subject Location Context Field
let subjectLocation: BTNLocation = BTNLocation.init()
subjectLocation.set(addressLine:"1 Fake Street")
subjectLocation.set(city:"1 Fake Street")
subjectLocation.set(country:"USA")
subjectLocation.addIdentifier("1234", forProvider: BTNIDProviderOpenTable)

// Set the Subject Location Context Field to the Context object
let context: BTNContext = BTNContext.init(subjectLocation: subjectLocation)
/** Subject Location **/
// Create a Subject Location Context Field
BTNLocation *subjectLocation = [[BTNLocation alloc] init];
[subjectLocation setAddressLine:@"1 Fake Street"];
[subjectLocation setCity:@"New York"];
[subjectLocation setCountry:@"USA"];
[subjectLocation addIdentifier:@"1234" forProvider:BTNIDProviderOpenTable];

// Set the Subject Location Context Field to the Context object
BTNContext *context = [BTNContext contextWithSubjectLocation:subjectLocation];

You can find the CocoaDocs for Location Context field here.


Journey Context

The Journey Context field provides information about anticipated travel. It requires the following properties:

  • startTime: The start time for the Journey
  • endTime: The end time for the Journey

Some Context fields can be extended to include additional information. Journey is an example of such a Context field, which can accept the following:

  • startLocation: A Location Context field that defines the starting point of the journey.
  • endLocation: A Location Context field that defines the ending point of the journey.

Below is some sample code setting up a Journey on a Context object & assigning the properties.

// Create the Journey Context Field
let journey: BTNJourney = BTNJourney.init()

// Set the start & end time properties of the Journey Context Field
journey.set(startTime: <#startDate#>)
journey.set(endTime: <#endDate#>)

// Create the Start & End Location Context Fields for the Journey
let origin: BTNLocation = BTNLocation.init(latitude: <#latitude#>, longitude: <#longitude#>)
let destination: BTNLocation = BTNLocation.int(latitude: <#latitude#>, longitude: <#longitude#>)

// Assign the origin & destination Location Context Fields to the Journey Context Field
journey.set(startLocation: origin)
journey.set(destinationLocation: destination)

// Set the Journey Context Field to the Context object, and don't stop believing!
let context: BTNContext = BTNContext.init(journey: journey)
// Create the Journey Context Field
BTNJourney *journey = [[BTNJourney alloc] init];

// Set the start & end time properties of the Journey Context Field
[journey setStartTime:<#startDate#>];
[journey setEndTime:<#endDate#>];

// Create the Start & End Location Context Fields for the Journey
BTNLocation *origin = [BTNLocation locationWithLatitude:<#latitude#> longitude:<#longitude#>];
BTNLocation *destination = [BTNLocation locationWithLatitude:<#latitude#> longitude:<#longitude#>];

// Assign the origin & destination Location Context Fields to the Journey Context Field
[journey setStartLocation:origin];
[journey setDestinationLocation:destination];

// Set the Journey Context Field to the Context object, and don't stop believing!
BTNContext *context = [BTNContext contextWithJourney:journey];

You can find the CocoaDocs for Journey Context field here.


Event Context

The Event Context field provides information about a specific time & location combination. It requires the following properties:

  • startTime: The date-time the event starts.
  • endTime: The date-time the event ends.

Similar to Journey, Event can be extended to include:

  • location: A Location Context field describing the location of the event.

Below is some sample code creating an Event and assigning it to a Context.

// Create the Location Context Field associated with the Event
let location: BTNLocation = BTNLocation.init(name:"<#Location Name#>", latitude: <#latitude#>, longitude: <#longitude#>)

// Create the Event Context Field, and assign the start & end time properties, as well as the Location Context Field to it
let event: BTNEvent = BTNEvent.init(startTime: <#startDate#>, endTime: <#endDate#>, location: location)

// Set the Event Context Field to the Context object
let context: BTNContext = BTNContext.init(event: event)
// Create the Location Context Field associated with the Event
BTNLocation *location = [BTNLocation locationWithName:@"<#Location Name#>" latitude:<#latitude#> longitude:<#longitude#>];

// Create the Event Context Field, and assign the start & end time properties, as well as the Location Context Field to it
BTNEvent *event = [BTNEvent eventWithStartTime:<#startDate#> endTime:<#endDate#> location:location];

// Set the Event Context Field to the Context object
BTNContext *context = [BTNContext contextWithEvent:event];

You can find the CocoaDocs for Event Context field here.


Artist Context

The Artist Context field provides information about a performance artist. This could include a musical act or a Broadway show. It requires one of the following properties be set:

  • Name: The name of the artist as a keyword to search against
  • Artist Identifier: A specific artist identifier for the Partner you wish to populate.

Note: Priority will always be given to the artist identifier, which is the more specific of the two options (i.e. Artist ID "1234" is more specific than "David Bowie"). We'll discuss Identifiers more in the next section.

Below is some sample code setting up an Artist and adding it to a Context object.

// Create a generic Context object
let context: BTNContext = BTNContext.init()

// Create the Artist Context Field and set the Name property
let artist: BTNMusicArtist = BTNMusicArtist.init(name: "Billy Joel")

// Set the Artist Context Field to the Context object
context.set(artist: artist)
// Create a generic Context object
BTNContext *context = [BTNContext context];

// Create the Artist Context Field and set the Name property
BTNMusicArtist *artist = [BTNMusicArtist artistWithName:@"Billy Joel"];

// Set the Artist Context Field to the Context object
[context setArtist:artist];

You can find the CocoaDocs for Artist Context field here.


Partner Specific Identifiers

Identifiers are unique id's that absolutely identify the intended entity to a specific partner. e.g. A Ticketmaster Artist ID, identifies the artist absolutely to Ticketmaster, but is not useful to many other providers. Where available, these IDs are helpful in making matches explicit.

You can add partner-specific identifiers to any context object, but Location and Artist make particularly strong use of them today.

Below is some sample code showing the assignment of an identifier for each of the Context fields outlined above:

/** Location Identifier **/
// Create a Location Context Field
let subjectLocation: BTNLocation = BTNLocation.init(latitude: <#latitude#>, longitude: <#longitude#>)

// Set an Identifier to the Location Context Field (specifying venue/restaurant/etc)
subjectLocation.addIdentifier("#identifier#>", forProvider: "<#button-marketplace-provider#>")
/** Location Identifier **/
// Create a Location Context Field
BTNLocation *subjectLocation = [BTNLocation locationWithLatitude:<#latitude#> longitude:<#longitude#>];

// Set an Identifier to the Location Context Field (specifying venue/restaurant/etc)
[subjectLocation addIdentifier:@"<#identifier#>" forProvider:@"<#button-marketplace-provider#>"];
/** Artist Identifier **/
// Create an Artist Context Field
let artist: BTNMusicArtist = BTNMusicArtist.init(name: "Billy Joel")

// Set an Identifier to the Artist Context Field (specifying artist)
artist.addIdentifier("<#identifier#>", forProvider: "<#button-marketplace-provider#>")
/** Artist Identifier **/
// Create an Artist Context Field
BTNMusicArtist *artist = [BTNMusicArtist artistWithName:@"Billy Joel"];

// Set an Identifier to the Artist Context Field (specifying artist)
[artist addIdentifier:@"<#identifier#>" forProvider:@"<#button-marketplace-provider#>"];

Once you've set an identifier to a Context field, you can set the Context field to the Context object as normal.

You can find the CocoaDocs for adding a Partner Specific Identifier here.


Partner Context Guide

Now that you understand the various types of Context that we offer, it's time to describe what Context each of the Buttons in our Button Marketplace requires! Below is a list of the Buttons in our Marketplace, and the Context options for each.

Merchant Supported Context Fields
Airbnb* Journey, Subject Location
Apple Retail No Context
BloomThat No Context
Boxed No Context
Caviar* User Location, Subject Location with Caviar merchant ID
Delivery.com* User Location, Subject Location with Delivery.com merchant ID
Delivery Hero* Subject Location, User Location
DoorDash No Context
Drizly* Subject Location, User Location
eBay No Context
Glamsquad User Location
Goldstar User Location
Handy Subject Location
Hotels.com* Subject Location with Hotels.com merchant ID, User Location, City Location
HotelTonight* Subject Location with HotelTonight merchant ID, User Location
iTunes Music Artist with iTunes merchant ID
Jet Item with Jet merchant ID
OpenTable* User Location, Subject Location with Opentable or Foursquare ID
Parking Panda Event
Quandoo User Location, Subject Location with Quandoo merchant ID
Resy* User Location, Subject Location with Resy merchant ID
Spring Item with Spring merchant ID
Ticketmaster* Subject Location with Ticketmaster venue ID, Artist with Ticketmaster artist ID
Uber* User Location, Subject Location, User Location and Subject Location
Zeel User Location

* indicates that there are multiple options for this Merchant.


Merchant Specific Context

See this guide for Merchant specific Context examples.