Skip to main content

Client libraries

The Upollo client libraries can be used identify users before they login, or if they use your application/site from multiple devices.

Client libraries are available for web (running in the browser), and for native iOS and Android mobile applications. They can be paired with a server library to protect logins, payments, etc.

Follow the quick start to get set up using a client library, or read on below for usage details.

Availability

Upollo has client libraries available for the following environments and languages:

  • Web (JavaScript or TypeScript): Available on NPM as @upollo/web or via our CDN.
  • iOS (Swift): Available via Cocoapods as Upollo
  • Android (Kotlin or Java): Available in the Maven Central Repository as ai.upollo:upollo-android

API

The main UpolloClient and its methods are outlined below. UserInfo, EventType and the response types are all protocol buffers. Their details are documented in upollo/userwatch-proto.

// To use:
// import UpolloClient from "@upollo/web";

export class UpolloClient {
// Accepts the project's public api key and an optional options object.
// 'options' can contain an optional 'url' to override the upollo api.
constructor(publicApiKey: string, options?: { url?: string });

// Inform Upollo of an event in your client application, and get back
// an immediate assessment of the user.
//
// Include any UserInfo you have, or an empty UserInfo if you have none.
//
// If your account is on the ‘free’ plan the `action` will always be
// `OUTCOME_PERMIT` and the `flags` array will be empty. Without
// upgrading you can use the dashboard to understand rates of account
// sharing and multi accounting.
async assess(
userinfo: uwproto_UserInfo | User,
eventtype: uwproto_EventType = uwproto_EventType.EVENT_TYPE_HEARTBEAT
): Promise<uwproto_AnalysisResponse>;

// Inform Upollo of an event in your client application, and get back
// a receipt in the form of an EventToken.
//
// Include any UserInfo you have, or an empty UserInfo if you have none.
//
// If your account is on the ‘free’ plan the `action` will always be
// `OUTCOME_PERMIT` and the `flags` array will be empty. Without
// upgrading you can use the dashboard to understand rates of account
// sharing and multi accounting.
async track(
userinfo: uwproto_UserInfo | User,
eventtype: uwproto_EventType = uwproto_EventType.EVENT_TYPE_HEARTBEAT
): Promise<uwproto_EventResponse>;

// A fast check for any known issues with the email.
//
// Returns any issues found, the type of email, as well as data on the
// company the email belongs to (if it is a company email).
async checkEmail(email: string): Promise<uwproto_CheckEmailResponse>;

// A fast check for any known issues with the password. The raw
// password is never shared beyond the Upollo client library; its hash
// is used instead.
async checkPassword(password: string): Promise<uwproto_CheckPasswordResponse>;

// A fast check for any known issues with the phone number.
//
// Returns any issues found as well as details about the type and carrier.
async checkPhone(phone: string): Promise<uwproto_CheckPhoneResponse>;
}

See the events types reference page for a full list of events types and guidance on how to use them.

Examples

constructor

When installing the library via NPM you can import the library to create the UpolloClient.

import { UpolloClient, EventType } from "@upollo/web";

const upollo = new UpolloClient("your-public-API-key");

If you don't use NPM or a dependency manager you can install Upollo in your website by including a script tag. Replacing {VERSION} with the latest version number on NPM

<script src="https://cdn.upollo.ai/web/{VERSION}/bundle.min.js"></script>

Once included, you will find the libary on the window.upollo object. Prefix everything inside the library with window.upollo. eg, new window.upollo.UpolloClient(..) or window.upollo.EventType like..

const client = new window.upollo.UpolloClient(publicApiKey);

assess

This example shows how you can nudge a user who is account sharing. You can use this on login to warn the user that others are using their account, and also remind them of benefits they can receive if they invite their friends to create accounts. A similar process can be applied in various other situations.

After calling assess(), inspect the flags in the response. Tailor your application's behaviour appropriately if the user is flagged for ACCOUNT_SHARING.

// Replace 12345 and person@example.com with the real ID and email of your user.
const analysis = await upollo.assess(
{ userId: 12345, userEmail: "person@example.com" },
EventType.EVENT_TYPE_LOGIN_SUCCESS
);
const flagTypes = analysis.flags.map((x) => x.type);
if (flagTypes.includes(FlagType.ACCOUNT_SHARING)) {
// Display a special message for the user who is account sharing.
// See our Blog for suggestions.
}

track

// Replace 12345 and person@example.com with the real ID and email of your user.
upollo.track(
{ userId: "12345", userEmail: "person@example.com" },
EventType.EVENT_TYPE_LOGIN_SUCCESS
);

Testing

To easily test your integration you can add +account_sharing or +multiple_accounts to the email address of API calls and it will return that flag.

For example foo+account_sharing@example.com will be flagged with ACCOUNT_SHARING and bar+multiple_accounts@example.com will be flagged with MULTIPLE_ACCOUNTS.

Upollo logoUpollo

Upollo empowers teams to learn more about their users so they can expand, retain, convert and upsell effectively.

Get Started for Free
About Us
  • About
  • Pricing
  • Blog
  • Contact
Community

© 2024

Proudly built in Sydney, Australia 🦘

PrivacyTerms