Button Developers

Button Links Setup

An overview of using Button Links to add Button content to web properties.

Button Links allow you to create a link that utilizes Button's routing and attribution systems to help a user shop in-app or on the web.

Here's an example:

https://r.bttn.io? \
  btn_url={https%3A%2F%2Fwww.brandwebsite.com} \
  &btn_pub_user={user_id_here} \
  &btn_ref={org-0000000000000000}
https://r.bttn.io?btn_url=https%3A%2F%2Fwww.brandwebsite.com&btn_pub_user=user-123&btn_ref=org-0000000000000000

Button Links accept the following query string parameters. All links must only contain ASCII characters and have properly encoded query strings.

Field

Required?

Definition

btn_url

Yes

The target Brand URL (url-encoded, including https)

e.g. https%3A%2F%2Fwww.brandwebsite.com

btn_ref

Yes

Your Button Organization ID (always starts with the prefix org-).

e.g. org-0000000000000000

This can be found in your Button dashboard.

btn_pub_user

Required for user rewards

Your user’s unique identifier. This value will be passed back to you in webhook requests associated with any downstream Brand activity such as orders or app-installs. Must be under 256 characters.

e.g. user-12345

Note: If you reward users for shopping activity you must include this value in order to know which user to reward.

btn_pub_ref

No

A Publisher reference value (e.g. click ID, campaign ID).

This value will be passed back to you in webhook requests associated with any downstream Brand activity such as orders or app-installs. Must be under 512 characters (decoded).

e.g. click-abc123

btn_desktop_url

No

A URL to redirect to if the user is on desktop. Leverage this parameter if you have a desktop network affiliate link you would like to use, otherwise exclude this parameter.

e.g. https://youraffiliateurl.com/tracking-info

Passthrough Values

Similar to how Publishers can use Button's iOS / Android SDK and have passthrough values persisted through Button, Publishers can pass a user ID or reference value on a Button Link.

Simply add the btn_pub_user parameter to pass through a user ID, or add the btn_pub_ref parameter to pass through a reference value (e.g. click ID, campaign ID).

Here's an example Button Link:

https://r.bttn.io? \
  btn_url={https%3A%2F%2Fwww.brandwebsite.com} \
  &btn_pub_user={user_id_here} \
  &btn_pub_ref={your_passthrough_value} \
  &btn_ref={org-0000000000000000}
https://r.bttn.io?btn_url=https%3A%2F%2Fwww.brandwebsite.com&btn_pub_user=user-123&btn_ref=org-0000000000000000&btn_pub_ref=your-ref

Button Links on Desktop

Button Links work equally on mobile & on desktop, but if you prefer to use an alternative link when a user is on desktop you can do so by providing a btn_destkop_url parameter — Button will then forward desktop users to that URL.

https://r.bttn.io?\
   btn_url={https%3A%2F%2Fwww.brandwebsite.com} \
   &btn_ref={org-0000000000000000} \
   &btn_desktop_url={https%3A%2F%2Fwww.affiliate-url-example.com}
https://r.bttn.io?btn_url=https%3A%2F%2Fwww.brandwebsite.com&btn_ref=org-0000000000000000&btn_desktop_url=https%3A%2F%2Fwww.affiliate-url-example.com

If you want Button to power deskop affiliation:

  • Simply use the Button Link on desktop as you would on mobile web (i.e. do not include the btn_desktop_url parameter).

Additional ways to use Button Links

Updated 8 months ago


Button Links Setup


An overview of using Button Links to add Button content to web properties.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.