Articles in this section

Setting up Unknown User Activation

Unknown User Activation makes it possible to learn about, message, and develop relationships with unidentified users of your mobile app and website. Before you begin setting it up, learn more about how it works in Unknown User Activation Overview.

# In this article

# API keys and JWT considerations

Unknown User Activation is available for use with Iterable's SDKs. At this time, Iterable's API does not include endpoints for Unknown User Activation.

When using Iterable's iOS, Android, or Web SDKs, remember that:

  • You'll need an Iterable API key (of type Web or Mobile).
  • For Iterable's Web SDK, JWT-enabled API keys are required. For Iterable's iOS and Android SDKs, they're optional but recommended.

JWT-enabled API keys are more secure than standard API keys because they require your server to authorize each user with a custom JWT token. Iterable's SDKs must request these tokens from your server for each user; Iterable can't generate them for you.

To use JWT-enabled API keys, set up a web service that Iterable's SDKs can call to get JWT tokens—this is required for all JWT-enabled API keys. Make sure your JWT server can issue tokens for SDK-generated unknown userId values, as well as for known userId or email values. You might also consider having your web service notify you whenever the SDK creates a new unknown user ID, so your server can issue JWT tokens for those users.

WARNING

Never embed a Server-side API key in a mobile or web app–they can be accessed by malicious users to access your project data.

# Setup tasks

To set up Unknown User Activation, complete the following tasks:

# Update your JWT server to issue JWT tokens for unknown users

When implementing Unknown User Activation, if your mobile and web apps use JWT-enabled API keys (required for Iterable's Web SDK, recommended for Iterable's iOS and Android SDKs), update your JWT server to return JWT tokens for unknown users created by Iterable's SDKs.

To identify an unknown user, Iterable's SDKs can only access the user ID that was generated by the SDK when the unknown user profile was created — not the server-assigned placeholder email for that same user. (In email-based projects, which identify users by email, Iterable assigns each unknown user a placeholder email address based on, but different from, the SDK-created user ID. However, the SDK doesn't have access to this email.)

Because of this, your JWT server must be able to issue JWT tokens as follows:

  • For apps and websites associated with userID-based and hybrid Iterable projects, your JWT server must be able to issue JWT tokens for:

    • SDK-generated userId values (UUID values; to authenticate unknown users).
    • userId values you assign to user profiles when converting them from unknown to known (to authenticate known users).

  • For email-based projects, your JWT server must be able to issue JWT tokens for:

    • SDK-generated userId values (UUID values; to authenticate unknown users created by the SDK).
    • Email addresses you assign to user profiles when converting them from unknown to known (to authenticate known users).

NOTE

For more information about using JWT-enabled API keys with Unknown User Activation, see API Keys and JWT Considerations.

# Define profile creation criteria

Before enabling Unknown User Activation in your mobile apps and website, make sure your marketing team has set up test criteria in Iterable that tells the SDKs when to create unknown user profiles in Iterable. When visitors do not meet the defined criteria (or if there is no criteria defined), they will continue to be stored only on-device or in-browser, and you won't see them in your Iterable project.

At runtime, Iterable's iOS, Android, and Web SDKs fetch these criteria, evaluate them, and create unknown user profiles for visitors who satisfy their requirements. For example, a simple criteria might specify to create unknown user profiles for visitors with a viewedProduct event.

The Web SDK fetches these criteria after you enable local data tracking (in response to user consent), and then refreshes them on each page refresh. The iOS and Android SDKs also fetch these criteria when you enable local data tracking (again, in response to user consent) or foregrounding, and then again each time the customer launches the app.

# Install or update an Iterable SDK

To use Unknown User Activation with Iterable's SDKs, you'll need to upgrade to one of the following SDK versions.

Related articles