Button Links Integration

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%2Fyouraffiliateurl.com%2Ftracking-info}

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 desktop 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

Links API Introduction — the Button Links API can be used to generate Button Links via an API call.