Logged-in user Email Request 🔗

access, email, user, retrieve, login

If the user of your program is logged in, you can use this feature to retrieve their email address. The syntax to be used is:

*database: request
	*what: email
	*success
		>> emailAddress = it["email"]
	*error
		>> errorReason = it["reason"]
		>> errorMessage = it["message"]

Now, in order to protect the privacy of GuidedTrack users, they may need to grant permission to your program so that it can get their email address. When this happens, they will see a modal like this:

Logged in user Email Request (1)

In the example shown, the program with the *database request has been named "University of Hobbiton" in Settings → Branding → Public Name. If you don't create a public name for your program, then the modal will display your program's name.

Your program users will only need to grant the program access to their email address one time, either:

  1. explicitly, by typing their email address when they were prompted to the first time that they run your program, or...
  2. implicitly, by creating a GuidedTrack account when running your program for the first time.

If the user clicks on the "Deny" button of the modal, the *database request will throw an error where the reason is "email access denied by user" and the message is "The user denied access to their login email address."

If your program does not require login and the user is not logged in, the *database request will also throw an error with the reason "user logged out" and message "The program cannot access the user's email address because they are logged out."

Remember, you can configure the login settings of your program in Settings → Login.

Here is a summary of the use cases described above:

  • If the user is not logged in, then the *database request returns an error.
  • If the user creates a GT account while running the program, then the *database request returns the user's email address without displaying the modal.
  • If the user already had an account and is logged in when running the program for the first time, then the *database request will first display a modal asking the user to grant access to their email address.
    • If the user clicks "Deny" in the modal, then an error is returned.
    • If the user clicks "Allow" in the modal, then the email address is returned.
  • If a user returns after having previously used the program and has already granted the program access to their email address from a *database request, then their email address is returned without displaying the modal.

Next: