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.

Web JavaScript

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

iOS Swift

// To use:
// import Upollo

public class UpolloClient {
  // Accepts the project's public api key and an optional options object.
  public init(publicApiKey: String, options: [String: String] = [:]) throws;

  // 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.
  public func assess(
    userinfo: UpProto_UserInfo,
    did eventtype: UpProto_EventType,
    callback: @escaping (UpProto_AnalysisResponse) -> Void,
    failure: @escaping (Error) -> Void);

  // 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.
  public func track(
    userinfo: UpProto_UserInfo,
    did eventtype: UpProto_EventType,
    callback: @escaping (UpProto_EventResponse) -> Void,
    failure: @escaping (Error) -> Void);
}

Android Kotlin

// To use:
// import ai.upollo.android.UpolloClient

class UpolloClient private constructor() {
    /**
     * Set up a [UpolloClient]
     *
     * @param ctx within which Upollo should gather information.
     * @param publicApiKey for your Upollo project.
     */
    constructor(ctx: Context, publicApiKey: String)

    /**
     * Set up a [UpolloClient] with special options.
     *
     * @param ctx within which Upollo should gather information.
     * @param publicApiKey for your Upollo project.
     * @param options to adjust Upollo's behaviour. There are currently no published options,
     *      so this is only needed if you are working with a member of the Upollo team who
     *      asks for a special option to be set.
     */
    constructor(ctx: Context, publicApiKey: String, options: Map<String, String>?)

    /**
     * Inform Upollo of an event in your client application, and get back an immediate
     * assessment of the user.
     *
     * 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 Upollo dashboard to see
     * the flagging and understand rates of account sharing and multi accounting. Upgrade to see
     * the outcome and flags.
     *
     * @param userinfo containing any details known about the current user, or empty if you
     *                 have none.
     * @param eventtype which occurred and instigated this request.
     * @return a typically incomplete future, which will later contain the analysis.
     */
    fun assess(userinfo: UserInfo, eventtype: EventType): CompletableFuture<AnalysisResponse>

    /**
     * Inform Upollo of an event in your client application, and get back a receipt in the
     * form of an EventToken.
     *
     * 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 Upollo dashboard to see
     * the flagging and understand rates of account sharing and multi accounting. Upgrade to see
     * the outcome and flags.
     *
     * @param userinfo containing any details known about the current user, or empty if you
     *                 have none.
     * @param eventtype which occurred and instigated this request.
     * @return a typically incomplete future, which will later contain the token.
     */
    fun track(userinfo: UserInfo, eventtype: EventType): CompletableFuture<EventResponse>

    /**
     * A fast check for any known issues with the email.
     *
     * Returns a CheckEmailResponse containing whether the email is valid, the type of issue found
     * (if the email is invalid), the type of email, the email address provider, as well as data on
     * the company the email belongs to (if it is a company email).
     *
     * @param email the user's email address.
     * @return a future CheckEmailResponse containing if the email is valid and other email details.
     */
    fun checkEmail(email: String): CompletableFuture<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.
     *
     * @param password the user's password.
     * @return a future CheckPasswordResponse containing whether the password is compromised.
     */
    fun checkPassword(password: String): CompletableFuture<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.
     *
     * @param phone the user's phone number.
     * @return a future CheckPhoneResponse containing if the phone number is valid, the type of
     * issue found (if the phone is invalid), country code, line type, carrier and a
     * consistently-formatted number.
     */
    fun checkPhone(phone: String): CompletableFuture<CheckPhoneResponse>
}

Android Java

// To use:
// import ai.upollo.android.UpolloClient;

class UpolloClient {
    /**
     * Set up a [UpolloClient]
     *
     * @param ctx within which Upollo should gather information.
     * @param publicApiKey for your Upollo project.
     */
    public UpolloClient(Context ctx, String publicApiKey);

    /**
     * Set up a [UpolloClient] with special options.
     *
     * @param ctx within which Upollo should gather information.
     * @param publicApiKey for your Upollo project.
     * @param options to adjust Upollo's behaviour. There are currently no published options,
     *      so this is only needed if you are working with a member of the Upollo team who
     *      asks for a special option to be set.
     */
    public UpolloClient(Context ctx, String publicApiKey,
            @Nullable Map<String, String> options);

    /**
     * Inform Upollo of an event in your client application, and get back an immediate
     * assessment of the user.
     *
     * 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 Upollo dashboard to see
     * the flagging and understand rates of account sharing and multi accounting. Upgrade to see
     * the outcome and flags.
     *
     * @param userinfo containing any details known about the current user, or empty if you
     *                 have none.
     * @param eventtype which occurred and instigated this request.
     * @return a typically incomplete future, which will later contain the analysis.
     */
    public CompletableFuture<AnalysisResponse> assess(UserInfo userinfo, EventType eventtype);

    /**
     * Inform Upollo of an event in your client application, and get back a receipt in the
     * form of an EventToken.
     *
     * 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 Upollo dashboard to see
     * the flagging and understand rates of account sharing and multi accounting. Upgrade to see
     * the outcome and flags.
     *
     * @param userinfo containing any details known about the current user, or empty if you
     *                 have none.
     * @param eventtype which occurred and instigated this request.
     * @return a typically incomplete future, which will later contain the token.
     */
    public CompletableFuture<EventResponse> track(UserInfo userinfo, EventType eventtype);

    /**
     * A fast check for any known issues with the email.
     *
     * Returns a CheckEmailResponse containing whether the email is valid, the type of issue found
     * (if the email is invalid), the type of email, the email address provider, as well as data on
     * the company the email belongs to (if it is a company email).
     *
     * @param email the user's email address.
     * @return a future CheckEmailResponse containing if the email is valid and other email details.
     */
    public CompletableFuture<CheckEmailResponse> checkEmail(String email);

    /**
     * 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.
     *
     * @param password the user's password.
     * @return a future CheckPasswordResponse containing whether the password is compromised.
     */
    public CompletableFuture<CheckPasswordResponse> checkPassword(String password);

    /**
     * A fast check for any known issues with the phone number.
     *
     * Returns any issues found as well as details about the type and carrier.
     *
     * @param phone the user's phone number.
     * @return a future CheckPhoneResponse containing if the phone number is valid, the type of
     * issue found (if the phone is invalid), country code, line type, carrier and a
     * consistently-formatted number.
     */
    public CompletableFuture<CheckPhoneResponse> checkPhone(String phone);
}

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

Examples

constructor

Web JavaScript

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

iOS Swift

import Upollo

var upollo: UpolloClient?
do {
    upollo = try UpolloClient(publicApiKey: "your-public-API-key")
} catch {
    print("UpolloClient setup failed: \(error)")
}

Android Kotlin

import ai.upollo.proto.EventType
import ai.upollo.proto.userInfo
import ai.upollo.android.UpolloClient

val upollo = UpolloClient(applicationContext, "your-public-API-key")

Android Java

import ai.upollo.proto.EventType;
import ai.upollo.proto.UserInfo;
import ai.upollo.android.UpolloClient;

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

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.

Web JavaScript

// 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.
}

iOS Swift

if let u = upollo {
  // Replace 12345 and person@example.com with the real ID and email of your user.
  u.assess(
    UpProto_UserInfo.with { i in
      i.userId = 12345
      i.userEmail = "person@example.com"
    },
    did: .loginSuccess
  ) { analysis in
    let flagTypes = analysis.flags.map { $0.type }
    if flagTypes.contains(.accountSharing) {
      // Display a special message for the user who is account sharing.
  // See our Blog for suggestions.
    }
  }
}

Android Kotlin

// Replace 12345 and person@example.com with the real ID and email of your user.
upollo.assess(
  userInfo {
    userId = 12345
    userEmail = "person@example.com"
  },
  EventType.EVENT_TYPE_LOGIN_SUCCESS
).thenAccept() { analysis ->
  val flagTypes = analysis.flagsList.map {it.type}
  if (flagTypes.contains(FlagType.ACCOUNT_SHARING)) {
    // Display a special message for the user who is account sharing.
  // See our Blog for suggestions.
  }
}

Android Java

// Replace 12345 and person@example.com with the real ID and email of your user.
upollo.assess(
    UserInfo.newBuilder().setUserId(12345).setUserEmail("person@example.com").build(),
    EventType.EVENT_TYPE_LOGIN_SUCCESS
).thenAccept((analysis) -> {
    Set<FlagType> flagTypes =
        analysis.getFlags().stream().map(Flag::getType).collect(Collectors.toSet());
    if (flagTypes.contains(FlagType.ACCOUNT_SHARING)) {
      // Display a special message for the user who is account sharing.
  // See our Blog for suggestions.
    }
});

track

Web JavaScript

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

iOS Swift

if let u = upollo {
  // Replace 12345 and person@example.com with the real ID and email of your user.
  u.track(UpProto_UserInfo.with { i in
          i.userId = "12345"
          i.userEmail = "person@example.com"
      }, did: .loginSuccess)
}

Android Kotlin

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

Android Java

// Replace 12345 and person@example.com with the real ID and email of your user.
upollo.track(
    UserInfo.newBuilder().setUserId("12345").setUserEmail("person@example.com").build(),
    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.