Referral SaaSquatch Help Center

This Mobile Widget reference includes details of the structure, available parameters, and an example of the request

To render the referral program in your iOS, Android, Windows phone, Cordova or Xamarin mobile project, you should include a customized URL in a WebView or iFrame component. This will load a mobile-responsive widget in your app which can track referrals as well as let your users refer their friends.

Base URL

Each of these customized URLs starts off with the same base URL section. To complete the URL, first replace {{tenant_alias}} with your program's Live or Test tenant alias.

app.referralsaasquatch.com/a/{{tenant_alias}}/widgets/mobilewidget

Each link is then customized with the following parameters:

Parameters

The base URL is then personalized with a combination of the parameters outlined below.

These parameters should be from the logged in user for whom you intend to load the mobile widget.

The parameters for the mobile widget are similar to those used the squatch.js init call.

tenantAlias Required Identifies which account to connect to. This is a super important parameter. For your app, you will get two tenant aliases -- one for test mode and one for live mode. Test mode alias are prefixed with test_, for example test_abhoihnqwet
userId Required A user ID from your system (must be unique for every user). We use this to uniquely track users, and lets us handle accounts that are shared between users.
accountId Required We use accountId to link a group of users together. See Shared vs Solo Accounts to see what you should use here.
paymentProviderId Required Unless explicitly setting this field it should be left as NULL. On payment provider programs this can be set to the Stripe Customer ID, Recurly Account ID, Braintree Account ID, or the Zuora Account ID. for free trials or freemium accounts.
accountStatus Optional

The status of the account identified by accountId.

  • Omit this parameter on programs configured for a payment provider.
  • Defaults to TRIAL
  • Possible values are TRIAL, FREE, PAID, or CANCELLED
  • Can also be updated using the REST API or Squatch.js.
referralCode Optional

The referral code of the person that referred this accountId (i.e. if Bob referred you, this value would be BOB)

  • Defaults to the first referral cookie value detected for FREE or TRIAL accounts.
  • Stores the value that is looked up with Coupon Autofill
  • If someone uses a referral code during checkout, set that value here.
  • Automatically calculated from integrations that use paymentProviderId
  • Will not update a value inside of a payment provider. Do not use when paymentProviderId exists.
  • Can also be set using the REST API or Squatch.js.
userReferralCode Optional The referral code to be shared by this userId.
  • Used to set a custom referral code for this userId.
  • Defaults to the first 15 alphanumeric characters of the user's first and last names.
  • Limited to 15 characters. Restricted to ASCII character codes 48-57, 65-90, and 97-122.
firstName Optional The user's first name
lastName Optional The user's last name
email Optional The e-mail address of the user. We use this to contact someone when they have a successful referral.
userImage Optional Defaults to Gravatar or, if unavailable, the user's initials. If you provide a absolute profile image URL the minimum image size is 80px x 80px. Requires Signed Requests.
fbShareImage OptionalDeprecated Defaults to no image for Facebook referrals. If you provide an absolute URL an image it will be used when a referral is made on Facebook. Minimum image size is 114px tall or 155px wide.
locale Optional The user's locale, used for Internationalization. The locale must be of the format language_COUNTRY where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore. Examples: en or en_US or zh_CN
mode Optional

Sets the display mode for the mobile widget being loaded. The mobile widget defaults to being loaded in a hosted mode.

  • Omitting this parameter (the default usage) loads the mobile widget in hosted mode.
  • Set mode to EMPTY to make POST requests to use Mobile Widget URL's functionality without displaying a widget to the user.
  • Not included in Signed Request calculations.

checksum Optional A HMAC-SHA2 checksum that is used to validate that data originated from your servers. For details, see the Signed Requests documentation. A signed request can use EITHER jwt or checksum but not both.
jwt Optional A JSON Web Token (JWT) that is used to validate that data originated from your servers. For details, see the Signed Requests documentation. A signed request can use EITHER jwt or checksum but not both.

Example

Parameters

Along with the Base URL (filled with out tenant alias) we select some test data to set for the parameters.

https://app.referralsaasquatch.com/a/test_345gh4545g23kj3/widgets/mobilewidget
?userId=123
&firstName=Bob
&lastName=Testserson
&accountId=abc
&paymentProviderId=NULL
&email=misterd%2Bmuser001%40example.com
&jwt={{calculated_JWT}}

Note: Make sure to URL encode any parameters (john@example.com vs john%40example.com)

Example Personalized URL

The parameters are then combined to create the unique URL. For the example parameters from the previous section, this will look like:

https://app.referralsaasquatch.com/a/test_345gh4545g23kj3/widgets/mobilewidget?userId=123&firstName=Bob&lastName=Testserson&accountId=abc&paymentProviderId=NULL&email=misterd%2Bmuser001%40example.com&checksum={{calculated_JWT}}

Embedding the URL in a WebView or iFrame

The unique URL can then be used to show the referral widget to your users.

Details about how to include a URL in a WebView or iFrame can be found through the following external references for a wide range of mobile development platforms.

Widget Theme Customization

Mobile widgets take full advantage of the Referral SaaSquatch theme system, so they can be completely customized to match your brand, theme, style, colors, fonts, animations and more. By default, standard themes come with a mobile-responsive template based upon Bootstrap 3, but custom themes like those used in the Shoeboxed referral program shown here can be customized complete with tabbed navigation.

Configuring Default mailto Behavior

The Email Share option in the referral widget uses the mailto link format. In order for the mailto link to work smoothly on both iOS and Android devices your app needs to be correctly configured to support the mailto event inside the app.

When using Swift 2.2.1 or 2.3 add the following code in your UIWebView’s delegate:

func webView(webView: UIWebView, shouldStartLoadWithRequest r: NSURLRequest, navigationType nt: UIWebViewNavigationType) -> Bool {
    if let scheme = r.URL?.scheme where scheme == "mailto" {
        UIApplication.sharedApplication().openURL(r.URL!)
        return false
    }
    return true
}

For Swift 3 use the following code with your WKWebView:

extension ReferralRewardViewController: WKNavigationDelegate {
    func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {

        let navigationUrl = navigationAction.request.url

        if let scheme = navigationUrl?.scheme, scheme == "mailto" {
            UIApplication.shared.openURL(navigationUrl!)
            decisionHandler(.cancel)
        } else {
            decisionHandler(.allow)
        }
    }
}

Create your WebViewClient:

public class MyWebViewClient extends WebViewClient {

    @Override
    public boolean shouldOverrideUrlLoading(WebView view, String url) {
       if(url.startsWith("mailto:")) {

           String stringUri = null;
           try {
               stringUri = URLDecoder.decode(url, "UTF-8");
           } catch (UnsupportedEncodingException e) {
               e.printStackTrace();
           }

           String[] url_variables = stringUri.split("&");
           String subject = url_variables[0].replaceFirst("mailto:\\?subject=", "");
           String body = url_variables[1].replaceFirst("body=", "");
           Intent intent = new Intent(Intent.ACTION_SEND);
           intent.setType("message/rfc822");
           intent.putExtra(Intent.EXTRA_SUBJECT, subject);
           intent.putExtra(Intent.EXTRA_TEXT, body);

           startActivity(Intent.createChooser(intent, "Send Email"));
       }
       else if(url.startsWith("http:") || url.startsWith("https:")) {
           view.loadUrl(url);
       }
       return true;
   }
}

Use the following code example to Load the Webview:

String url = "https://app.referralsaasquatch.com/widgeturl";
WebView widget = (WebView) this.findViewById(R.id.webView);
widget.getSettings().setJavaScriptEnabled(true);
widget.setWebViewClient(new MyWebViewClient());
widget.loadUrl(url);

Looking for something special?

Still couldn't find it?