SaaSquatch Help Center

This tutorial will walk you through building a custom widget using the SaaSquatch GraphQL API

🔗 Getting Started with GraphQL

In order to start using GraphQL, you'll need to do be using a GraphQL client. There are GraphQL clients for:

  • C# / .NET
  • Clojurescript
  • Go
  • Java / Android
  • JavaScript
  • Swift / Objective-C iOS
  • Python

List of GraphQL clients.

🔗 Security

If you're building a custom widget, you're probably doing it on mobile or in the browser. To simplify authentication, we recommend making GraphQL calls authorized as the end user.

To do enable authorization, generate a JSON Web Token (JWT) for your user using you tenant API key on the server.

Authorization: Bearer {JWT}


Important - Never embed your API Key in your mobile app, website or javascript. If it is exposed, an attacker can get full access to your site.

🔗 Looking up the User

The easiest way to get data in a custom widget is to use the special viewer property to lookup the user that is currently authorized.

🔗 Showing a list of rewards

You can look up either a list of rewards to show people what they've earned from your programs.

  • prettyValue vs value - When building custom widgets it's usually best to use the prettyValue for rewards, since that will format and localize the reward value into something human-readable. Note that there also pretty fields for available and expired values.
  • value vs availableValue - The value of a reward may change due to it being expired, or cancelled, or redeemed. If you want to show a sense of progress, you can show lifetime earned amount.

🔗 Showing who referred a user

If someone has been referred, it's common to show them "You were referred by Jon Snow" in the user interface. To look that up, use the referredByReferral connection to find out more about the Referral.

🔗 Showing a list of referrals

To show someone their list of referrals, and any rewards earned because of those referrals, use the referrals connection on a user.

Note that you'll need to include your programId in this call only if one user is making referrals across different referral programs, and you want to filter them out.

🔗 Update a user

You can also do a complete upsert instead of using the user upsert from Squatch.js or our REST API. Only the fields that are included are updated, so you can add new fields, or add new segments, without removing overriding previous values.

In this example Sansa becomes a bolton, is added to a new segment, updates her last name, and is flagged as married.

🔗 Look up reward configuration

You can advertise what people will earn from your program by looking up the program by id, and then looking up the program's rewards. Every program has a different set of reward keys, so make sure to look this up when you're setting up your program.