Mobile Widget Reference

This approach has been deprecated and will be removed in 2021. Please use the REST API, GraphQL API or Android SDK to create mobile widgets

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) Only works with Classic referral programs Defaults to the first referral cookie value detected for FREE or TRIAL accounts. (Note: Only works with 3rd party cookies, not 1st party cookies) 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](/developer/squatchjs/signed-requests/) 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.

• Android Webview
• iOS Webview
• Xamarin Webview
• Cordova Webview
• Windows Phone Webview

🔗 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 Behavior

The Email and SMS Share options in the referral widget uses the mailto: and sms: link formats.

Your app needs to be correctly configured in order for the mailto: and sms: links to work smoothly on both iOS and Android devices from within an webview.

🔗 Configure iOS Links

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" || scheme == "sms" || scheme == "whatsapp" {
        UIApplication.sharedApplication().openURL(r.URL!)
        return false
    }
    return true
}

For Swift 3 add the following code to your ViewController.swft:

func webView(_ webView: UIWebView, shouldStartLoadWith r: URLRequest, navigationType nt: UIWebViewNavigationType) -> Bool {
    if let scheme = r.url?.scheme, scheme == "sms" || scheme == "mailto" || scheme == "whatsapp" {
        UIApplication.shared.openURL(r.url!)
        return false
    }
    return true
}

Add the following to your Info.plist:

LSApplicationQueriesSchemes
  Item 0 - String - sms
  Item 1 - String - mailto
  Item 2 - String - whatsapp

🔗 Configure Android Links

Configure the URL actions:

public class MyWebViewClient extends WebViewClient {

        @Override
        public boolean shouldOverrideUrlLoading(WebView view, String url) {
            String stringUri = null;
            try {
                stringUri = URLDecoder.decode(url, "UTF-8");
            } catch (UnsupportedEncodingException e) {
                e.printStackTrace();
            }

            if(url.startsWith("mailto:")) {

                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("sms:")) {

                String[] url_variables = stringUri.split("&");
                String body = url_variables[1].replaceFirst("body=", "");
                Intent smsIntent = new Intent(Intent.ACTION_VIEW);
                smsIntent.setType("vnd.android-dir/mms-sms");
                smsIntent.putExtra("sms_body", body);
                startActivity(smsIntent);
            }
            else if (url.startsWith("whatsapp:")) {

                String[] split_string = stringUri.split("=");
                String text = split_string[1];
                Intent sendIntent = new Intent();
                sendIntent.setAction(Intent.ACTION_SEND);
                sendIntent.putExtra(Intent.EXTRA_TEXT, text);
                sendIntent.setType("text/plain");
                startActivity(sendIntent);

            }
            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);