Branch for Advocate — Technical Reference

Your Advocate program can integrate with Branch Metrics.

This technical reference explains the specific fields, features, API calls and functionality that is used in the integration. Just getting started? Learn how to Integrate with Branch for Advocate Programs.

Link handling behaviors

After the Branch integration is configured, link-handling behaviors will change.

  • Referral links (e.g., will begin redirecting to Branch links
  • Advocate will create branch links dynamically and set values for data, channel, tags, and desktop_URL.
  • Branch deep link data will include details of the referral code, advocate, and reward. See the field reference below for an example.
  • Analytics tags will be added to help you track the performance of different platforms.
    • channel: The referral medium. Value can be 1 of: FACEBOOK, TWITTER, EMAIL, DIRECT, REMINDER, or UNKNOWN.
    • tags: The source of the referral. Value may be 1 of: STANDARD, MOBILE, or UNKNOWN. will send all link clicks through Branch, but will continue to redirect desktop traffic to your program’s landing page. This is done by setting the Branch value for desktop_url. If you set a desktop url for your app in Branch, it will be overwritten.

Field reference

When creates links dynamically in Branch, we include a number of metadata fields in the data field. These include fields from the User, Referral Code and Reward objects.

Field Type Description
sq_id string The customer advocate's user ID. This allows you to look up the user in your own system.
sq_accountId string The customer advocate's account ID. This allows you to look up group or company info.
sq_firstName string The customer advocate's first name.
sq_lastName string The customer advocate's last name.
sq_imageUrl string The customer advocate's profile image URL. Note that unlike the user's imageUrl that is used other places in Advocate, if this field is set to null it won't actually be null. Instead, when set to null it is replaced by an gravatar link that is automatically generated based on a hash for the customer advocate's email address. If you want to detect for null images instead, you should look for its gravatar, or not use this field and look up the value in your user database.
sq_referralCode string The customer advocate's referral code. This is necessary to attribute the referral.
sq_amount string The amount of the referred friend's reward. We map this abstract field to other rewards fields that can be looked up via the API or UTT.
  • For rewards of type TIME_CREDIT and CREDIT, this field is equal to the reward field called credit
  • For rewards of type PCT_DISCOUNT, this field is equal to the reward field called discountPercent
  • For rewards of type FEATURE, this field is equal to the reward field called quantity
  • For rewards of type GIFTCODE, this field is empty
sq_unit string The unit of the referred friend's reward. For example, in a 10% off referral program, this would be PERCENT.
sq_type string The type of the referred friend's reward. One of: PCT_DISCOUNT, TIME_CREDIT, FEATURE, CREDIT, GIFTCODE

Example deep link

When creates a link dynamically in Branch, the resulting deep link will include analytics tags, redirects, and custom metadata. Here’s an example.

    "code" : "BRITTANYTEST",  
    "$desktop_url" : "http\:\/\/\/a\/test_a6whcgrt0vcw3\/widgets\/referral?code=BRITTANYTEST&referralMedium=DIRECT&referralSource=STANDARD",  
    "sq_accountId" : "55a43496ebbaff9cf86443d3",  
    "sq_amount" : "10",  
    "sq_firstName" : "Brittany",  
    "sq_id" : "55a43496ebbaf01cebac42cb",  
    "sq_imageUrl" : "http\:\/\/\/avatar\/77af7eba41d1ccad2bf2c13704637c25?d=mm",  
    "sq_lastName" : "Test",  
    "sq_referralCode" : "BRITTANYTEST",  
    "sq_type" : "PCT_DISCOUNT",  
    "sq_unit" : "PERCENT",  
    "~channel" : "DIRECT",  
    "~tags" : ["STANDARD"],  
    "~creation_source" : "API",  
    "+is_first_session" : false,  
    "+clicked_branch_link" : true