Mobile Web Order Reporting

Confirm ButtonJS Implementation

Make sure that ButtonJS has already been added to your base HTML template (i.e. ButtonJS must be on the checkout confirmation page where you have access to order details). It is critically important that ButtonJS is present on the page the user has been initially linked to - otherwise, we will not be able to track and attribute any orders stemming from that link. If it is not, add the below code:

<script>
window.ButtonWebConfig = {
  applicationId: 'app-xxxxxxxxxxxxxxxx', // Replace app-xxxxxxxxxxxxxxxx with your App ID from the Button Dashboard https://app.usebutton.com
  enableSmsCollection: true // Optional, used when integrating with SMS for PostTap
};
(function(u,s,e,b,t,n){
  u['__bttnio']=b;u[b]=u[b]||function(){(u[b].q=u[b].q||[]).push(arguments)};t=s.createElement(e);n=s.getElementsByTagName(e)[0];t.async=1;t.src='https://web.btncdn.com/v1/button.js';n.parentNode.insertBefore(t,n)
})(window, document, 'script', 'bttnio');
</script>

Create Order Object

Construct a set of objects that contain your line item and order details, ultimately creating a final order object which you will report to Button below.

The structure of this order object is nearly identical to orders reported server-side. The only difference is that reporting the btn_ref, Button's opaque tracking token, is not needed. As long as ButtonJS was on the page the user's landing page, it is picked up automatically by the library.

📘

Property Definitions

Please view the definitions below for each displayed field.

Jump

// Create line item 1
let lineItem1 = {
  identifier: 's6-18860485p21a12v65a13v54',
  sku: 's6-18860485p21a12v65a13v54',
  description: 'Keep Calm and Droid On - R2-D2 Art',
  category: ['Home Decor'],
  total: 3799,
  quantity: 1,
  attributes: {
    promo_code: 'maythefourthbewithyou',
    brand: 'Ariel Sinha'
  }
};

// Create line item 2
let lineItem2 = {
  identifier: 's6-19791302p77a224v780',
  sku: 's6-19791302p77a224v780',
  description: 'Leia Skywalker Bar Stool',
  category: ['Furniture'],
  total: 39800, // total = item unit price * quantity
  quantity: 2,
  attributes: {
    promo_code: 'maythefourthbewithyou',
    brand: 'Ariel Sinha'
  }
};

// Create a customer (email is lowercased, then hashed via SHA-256)
let customerObject = {
  id: 'customer-1234',
  email_sha256: '814FA0649630F8B219E30952E92FEEFB70005C386C726F92FA93D1C18018EADE',
  device_id: '12345678-1234-5678-1234-567812345678',
  is_new: true,
};

// Create the order and add optional properties
// Order total will be calculated from line-item totals
let order = {
  order_id: 'order-1a2b3c',
  customer_order_id: 'receipt-123456',
  currency: 'USD',
  purchase_date: '2020-07-301T12:00:00Z',
  customer: customerObject,
  line_items: [lineItem1, lineItem2]
};

Report the Order

After creating the order object, you can then report your order to Button. If so desired, you can include a callback function as the third argument - however this is entirely optional.

// Report the order directly to Button.
bttnio('reportOrder', order, optionalCallback)

🚧

Report All Orders

Button recommends you call this method for each order tracked on your website. Attempting to conditionally fire this method (i.e. based on the presence of tracking information) could result in unexpected issues.

Button's system is designed to detect and subsequently process orders based on whether Button was involved with the user's activity on site.

Conversion Field Definitions

When reporting client-side, our Order API endpoint accepts an order object with the following properties:

Order Object Properties

• total: Total value of the order. Includes any discounts, if applicable. Must exclude VAT, all other taxes, surcharges and any additional costs such as delivery. This value represents the commissionable total. Must be an integer >= 0. Example: 1234 for $12.34.
• currency: Three-letter ISO currency code as specified in ISO 4217.
• order_id: The Order ID unique to this order. Treated as an ASCII string. 255 character maximum.
• purchase_date: ISO-8601 string representing the time the purchase was made by the user. Example: 2019-07-01T00:00:00Z
• customer_order_id: The customer-facing order ID. Treated as a UTF-8 string. 255 character maximum. Note: Use this field to report the order identifier as communicated to the customer.
• partner_order_channel: The channel in which the user transacted. Accepted values for this field are app and webview.
• customer:
  • id: The ID for the transacting customer in your system.
  • email_sha256: The SHA-256 hash of the transacting customer's lowercase email, as a 64-character hex string. Note: The value of the e-mail address must be converted to lowercase before computing the hash. The hash itself may use uppercase or lowercase hex characters.
  • is_new: A Boolean value indicating whether or not the customer has previously made a purchase. Pass true if this is their first purchase, otherwise pass false.
• line_items: An array of the line item details that comprise the order. Note: while optional for integration with Button, line items are required to partner with many Button Publishers.
  • identifier: The unique identifier for this line item, within the scope of this order. This must be unique across all line-items within the order. We suggest using the SKU or UPC of the product.
  • sku: The Stock Keeping Unit of the line item. A Brand-specific identifier for the line item. String with a maximum length of 255.
  • upc (if applicable): The Universal Product Code of the line item. Also referred to as UPC-A and GTIN-12. UPC-E (8-digit) codes should be converted to 12-digit codes. String with 12 numeric digits.
  • quantity: The number of unique units represented by this line item. Must be an integer > 0. Defaults to 1.
  • total: The total cost of all items in this line item expressed as an integer representing the lowest currency denominatio (e.g. if 3 bananas were purchased for $3.00 each, total would be 900, representing a product unit cost of 300 pennies - the lowest USD currency denomination - multiplied by 3 the quantity for the line-item). Must be net of any discounts or taxes and represent the value a Brand expects to commission on. Must be an integer > 0.
  • category: The category of the line item. An ordered list of strings, starting with the topmost (or most general) category. The total number of subcategories is capped at 7. Example: ["Electronics", "Computers", "Laptops", "Accessories", "Bags"].
  • description: Text describing the line item.
  • attributes: A key/value store for strings to specify additional information about a line item (e.g. promo_code). Speak to your Button representative about the specific data fields necessary for your integration.