Glossary

Application

An Application represents a single iOS, Android, or Mobile Web app. It holds a collection of metadata about the app and is used to configure it with Button's systems. For instance, before the SDK can be integrated, you must add information about your Application to our Dashboard and supply the ID we assign it back to the SDK.

As a Publisher Partner, all Buttons you create will be belong to an Application.

As a Merchant, all Campaigns you create will be scoped to an Application. This way Button knows how to properly link incoming Users to your app via the app's Deeplink scheme.

An Application also supports Configurations, which allow partners to specify environment-specific attributes. For instance, an iOS Application might have a different Bundle Identifier for development, staging, and prod.

Account

An Account, much like a real bank Account, holds commissions earned and owed from activity on Button.

An Organization will have one or more Accounts. Each Account is associated with a single currency and is designed to handle any commissions distributed in that currency for that Organization.

Advertising Id

This refers to the platform-specific Advertising Identifier on a User's Android or iOS device. This is know as an IDFA on iOS and AAID on Android. The lifetime of an Advertising Id is platform and user behavior dependent.

Affiliate System

Button's Affiliate System covers the tracking of a User from Publisher app to Commerce app to purchase and the subsequent distribution of commission to relevant parties.

A unique Attribution Token is generated every time a Publisher requests a Button, is passed through a Deeplink when a user taps a Button, and, to close the loop, is reported back to Button along with order details by the Merchant through their Order Reporting integration when the User makes a purchase.

Rules can be configured per partner to stipulate the distribution of commissions. For instance, an Attribution Window can be set to limit the maximum valid time between a Button being tapped and an order being made.

API Key

An API Key can be thought of as the password for authenticating information going into Button. Specifically, it's used to authenticate as a client of Button's API. The API Key is an Organization's most secret token and can be used to incur liability on behalf of the Organization.

You can find your API Key in the dashboard.

Approvals

Because Button maintains a marketplace of Merchants and Publisher Partners, we have the notion of an Approval to manage consent from either side of the market. Before a Publisher is able to use a Button they've configured with one or many Merchants, they'll need submit a request for approval. Once approved, the Button will be ready for production use.

Performance metrics will not be reported between partners that aren't mutually approved for each other.

Attribution Token

Button uses a string token to track a User's journey from a Publisher Partner application to a Merchant application. Button issues an Attribution Token to a Publisher for use with one of their Buttons. When a User taps that Button, the token will be included in the Deeplink and received by the SDK embedded in the Merchant's app. If the User completes an order, the token will then be reported back to Button along with the order so Button has a view of the entire journey of a User.

The Attribution Token is also referred to as:

Attribution Tokens are commonly prefixed with srctok-, org-, or aff-.

Attribution Window

A rule for distributing commissions in our Attribution System.

The Attribution Window configures how much time may pass between a Button being tapped and an order being driven with the corresponding Attribution Token to be considered valid and to subsequently pay out commissions. The Button default value for this is 7 days.

Attribution Count

A rule for distributing commissions in our Attribution System.

The Attribution Count configures how many orders can be attributed to the same Deeplink. The Button default value for this is 1.

Audience

Another term for a Publisher Partner.

btn_ref

Another term for an Attribution Token.

Button API

The Button API is an interface that allows partners to interact with our systems programmatically. For instance, Merchants use our API to notify us when Orders have been placed on their platform.

To make requests to our API, register for an account on our dashboard and grab your API Key. This key is used to authenticate all requests you make against our API.

Our API is securely exposed over HTTPS at api.usebutton.com:443. To authenticate, just pass along your API Key as the HTTP Basic Auth username. To make communicating with the API even simpler, we've released client libraries for node.js, python, and ruby.

For more information about our API, check out our API Docs. We also have an interactive tool you can use to validate proper usage of our API.

Button

We refer to a Button as a rendered UI element in a Publisher app or mobile site. A Button can Deeplink directly to a page in a Merchant app or display available Inventory inline through a Commerce Card.

A given Publisher may wish to create many individual Buttons to place at various locations in their application. Each Button can be set up with rules that determine which Merchants will be shown and under what conditions. For instance, a Publisher can show a restaurant reservation service only if the time is between 5pm and 8pm and a delivery service otherwise by setting up the proper connections and rules in their dashboard.

Even though a Merchant can offer their services with a Button, we don't refer to them has having Buttons. Instead, Merchant's can expose and configure their services with a Campaign.

Campaign

We refer to a Campaign as the branding, copy, Inventory, and deeplinks a Merchant wishes to display when they're rendered in a Button. A Campaign can be configured to link directly to a location in a Merchant's app or can display relevant Inventory to that Button inline through a Commerce Card. Rules can be added to a Campaign that give the Merchant control over when it will be rendered in a Button.

Campaigns can be managed in your dashboard.

Commerce Card

A Commerce Card is a modal rendered after a tap on a Button that has been fulfilled by a properly configured Campaign. Commerce Cards come in a variety of flavors, but are generally used to display Inventory inline with the Button that can help route a User to a meaningful page in the Merchant's app.

List Commerce Card

A List Commerce Card displays Inventory in a list format. It can render a list of Inventory as either un-grouped (for instance, a list of movie times for nearby theaters) or grouped (that same list but grouped by movie theater).

Product Commerce Card

A Product Commerce Card displays Inventory of a single item with a large corresponding asset, for instance a menu item at a nearby restaurant with a picture of the meal.

Commerce Partner

Another term for a Merchant.

Context

Context is a collection of attributes supplied by the Publisher application to Button so we can render the most useful Button possible. It may provide the latitude and longitude of the User or the specific id of a venue (like Madison Square Garden) so we can display nearby concerts.

Core Funnel

Button's Core Funnel refers to the metrics we collect over the course of a User's interaction with Buttons or our Affiliate System. These metrics are reported in the Performance section of your dashboard

Dashboard

We offer a dashboard that exposes Button's core functionality to both Publishers and Merchants. It reports the performance metrics defined by our Core Funnel and enables self-serve configuration of Buttons, Campaigns, and more.

A Deeplink is like a link on the web but that instead routes to a specific location in a mobile app. Deeplinks can additionally carry information from one app to another. We use this property to send the Attribution Token from Publisher app to Commerce app as a part of our Affiliation System.

A Deeplink to a Pet Food retailer called PetGrub may look something like petgrub://dogs/treats/bacon-bits?btn_ref=srctok-XXX.

Deferred Deeplinking

Another term for Post-Install Linking

Inventory

Inventory refers to the categories or items a Merchant would like to offer a User in a Commerce Card. A Merchant can configure the Inventory for a Campaign in their dashboard.

Dynamic

Dynamic Inventory is queried for every time a Commerce Card is loaded for a user. Button will make a request to an API provided by the Merchant with certain attributes from the User's Context as arguments. The Inventory returned by the Merchant is then fed back to the Commerce Card for rendering.

An excellent use for Dynamic Inventory would be looking up nearby coffee shops based on a User's latitude and longitude.

Static

Static Inventory allows Merchants to declare a set of Inventory that is always used when a Campaign's Commerce Card is rendered.

This is useful in scenarios where relevant Inventory is known a priori or an API integration isn't economical.

Merchant

A Merchant is a recipient of traffic from one of Button's Publisher Partners for a product of service they offer.

As a Merchant, you showcase your offering by creating a Campaign, which configures the branding, copy, Inventory, and deeplinks that will be rendered in a Publisher's App.

Merchants are additionally responsible for reporting Orders that occur on their platform back to Button via our API.

Merchants are also referred to as "Recipients" or "Merchants".

Order Reporting

Order Reporting closes the loop on a User's journey through Button's Affiliate System.

If a User deeplinks to a Merchant App and completes an Order, the Merchant is responsible for reporting that order back to Button. Along with other information about the order, the Merchant should include the Attribution Token they received from the Deeplink so Button knows who drove the order.

Order Reporting is accomplished by sending requests to Button's API (and most conveniently by using one of our Client Libraries for node.js, python, or ruby).

You can:

Order

An Order is Button's record of a completed transaction in a Merchant's app along with some data relating it to our Affiliate System. It includes fields like the total value of the order, order currency, line items purchased in the order, and when the order will be considered "finalized" (unable to be adjusted or deleted).

Button receives information about an Order through the Order Reporting process.

Organization

An Organization is how Button models one of its partners. An Organization can identify as a Merchant or a Publisher or both. Everything in our system, including Buttons, [Campaigns][#campaign], and Orders are scoped to an Organization.

Every user of our Dashboard belongs to an Organization.

Post-Install Linking

Post-Install linking refers to the process of completing the intent to reach a page in a Commerce app when something else blocks the process. A classic example of this is tapping a Button on a mobile web site and being directed to the app install flow for that app. Button can't push the deeplink to the app once it finishes installing, so we instead use weak signals about the User to fingerprint them when they leave the Publisher app and attempt to match that with similar signals when the enter the freshly installed Commerce app. If a match is found, we complete the Deeplink.

Merchants will need to integrate our SDK to support Post-Install Linking.

Publisher

A Publisher Partner has an audience they'd like to expose a relevant Merchant's services to.

As a Publisher Partner, you configure Buttons you'd like to place at various positions in your app or mobile web site. Rules can be set on a Button to trigger which Merchant gets shown in a Button when and with what Inventory.

Recipient

Another term for a Merchant.

referrerToken

Another term for an Attribution Token.

SDK

The Button SDK (Software Development Kit) is code that can be integrated into a mobile application or website by either a Merchant or Publisher Partner. It can be thought of as a utility belt that makes it as easy as possible for a partner to integrate with Button and take advantage of all our functionality.

For example, the SDK handles reporting all the key metrics Button collects as a part of our Core Funnel. Additionally, as a Publisher Partner the SDK will provide utilities for rendering Buttons and Commerce Cards, and as a Merchant features like Post-Install Linking and Attribution Token handling.

Tracking Token

Another term for an Attribution Token.

Transaction

A Transaction is a record in Button's Affiliate System that captures the distribution of commissions from a qualifying event (like an app install or order placement). A list of relevant Transactions for your [Organization] can be found in your dashboard.

Universal Links are http-style URLs that will Deeplink a User to specific content of an app if they have it installed and fall back to a mobile-web equivalent page if they do not.

For example, https://resy.com/cities/ny/charlie-bird will open in the Resy App if the User has it installed, or their browser otherwise.

For more information, see our guide on setting up Universal Links.

User

We refer to the User as the person who taps a Button in a Publisher app, gets Deeplinked to a Merchant app, and ideally makes an Order. They are the ultimate consumer of any software or services provided by Button or one of its partners.

User Identifier

A User Identifier is a partner-specific identifier that can be set with the SDK. The provided User Identifier will then be associated with the current session's Attribution Token and reported back to partners where relevant so that they can map Button events to their own user namespace.

Transactions, for instance, will report any associated User Identifier.

Webhook

A Webhook is a request by a partner to be notified when an event occurs in Button's Attribution System. For example, partners may declare their desire to receive an HTTP request at a specific URL whenever a relevant Transaction has been created in our system.

Because partners have to expose an endpoint on the open internet for Button to send requests to, it is highly encouraged they secure the endpoint using their Webhook Secret. This guarantees that:

  1. The request is authentic and came from Button's servers
  2. The request contents were not tampered with as they were sent over-the-wire.

Mission-critical business logic is often behind a webhook request, and failing to verify the integrity of information being sent can lead to fraud and destruction of data. All partners setting up a webhook should verify the integrity of the request by using their Webhook Secert and following our guide.

Webhooks can be configured in the dashboard.

Webhook Secret

A Webhook Secret is created for every Webhook configured in the Dashboard. This unique secret is used to cryptographically verify incoming payloads to your system.

Webhook Secrets can be found in the Dashboard on the Details page of a particular Webhook.