Building a custom Widget using GraphQL
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
🔗 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}
Related
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.
prettyValuevsvalue- When building custom widgets it's usually best to use theprettyValuefor 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.valuevsavailableValue- 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.