react-native-iterate

Iterate for React Native

Iterate surveys put you directly in touch with your app users to learn how you can change for the better—from your product to your app experience.

Run surveys that are highly targeted, user-friendly, and on-brand. You’ll understand not just what your visitors are doing, but why.

Platforms Supported

• iOS
• Android

Install

With yarn

$ yarn add react-native-iterate

With npm

$ npm install --save react-native-iterate

Install peer dependencies

We rely on only one peer dependency, if you already have it in your app you can skip this step.

• react-native-webview - used to display the survey

With yarn

$ yarn add react-native-safe-area-context react-native-webview

With npm

$ npm install --save react-native-safe-area-context react-native-webview

Install storage facility

When you initialize Iterate you provide it with a storage facility that's used to save the API key as well as any additional user data set by calling the identify method. We recommend using an encrypted storage facility like react-native-encrypted-storage, however you can also use async-storage or provide your own, the only requirement is that it complies with our StorageInterface.

export interface StorageInterface {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
}

With yarn

$ yarn add react-native-encrypted-storage

With npm

$ npm install --save react-native-encrypted-storage

Install safe area provider

On mobile devices the safe area represents the portion of the view that is suitable for UI to be displayed. Rather than requiring an additional peer dependency, you pass in your own method of providing the safe area. We recommend you use react-native-safe-area-context, however you can provide your own method that conforms to the interface () => {top: number, bottom: number, left: number, right: number}

With yarn

$ yarn add react-native-safe-area-context

With npm

$ npm install --save react-native-safe-area-context

Link native dependencies

From react-native 0.60 autolinking will take care of the link step and you can safely skip

React Native modules that include native Objective-C, Swift, Java, or Kotlin code have to be "linked" so that the compiler knows to include them in the app.

$ react-native link react-native-webview

Link your storage facility

$ react-native link react-native-encrypted-storage

Link your safe area provider

$ react-native link react-native-safe-area-context

Install pods

For iOS you need to run pod install to complete the installation. Within the ios library of your app, run the following

$ pod install

Usage

Within your app, surveys are shown in response to events. An event can be anything from viewing a screen, clicking a button, or any other user action. You use the Iterate SDK to send events to Iterate, then from your Iterate dashboard you create surveys that target those events.

Quick start

Create your Iterate account if you haven't already.

• Create a new survey and select "Install in your mobile app"
• Go to the "Preview & Publish" tab and copy your SDK API key
• Call Iterate.Init with your apiKey, safeArea function, and storage, then wrap your App in the <SafeAreaProvider> (if using react-native-safe-area-context) and <IterateProvider> components

import Iterate from 'react-native-iterate';
import SecureStorage from 'react-native-encrypted-storage';
import { SafeAreaProvider, useSafeAreaInsets } from 'react-native-safe-area-context';

const App = () => {
  React.useEffect(() => {
    Iterate.init({
      apiKey: apiKey,
      safeArea: useSafeAreaInsets,
      storage: SecureStorage,
    });
  }, []);

  return (
    <SafeAreaProvider>
      <IterateProvider>
        { // Your application views }
      </IterateProvider>
    </SafeAreaProvider>
  )
}

export default App;

• Implement events

Here's an example of an event being fired when the user views the activity feed screen

import Iterate from 'react-native-iterate';

const ActivityFeed = () => {
  useEffect(() => {
    Iterate.sendEvent('viewed-activity-feed');
  }, []);

  // ...rest of component
}

• Create your survey on iteratehq.com and target it to that event
• Publish your survey and you're done 🎉

Previewing your survey

You'll likely want to preview your survey before publishing it so you can test that everything works correctly. When previewing a survey you'll be able to see a survey before it's published. When previewing a survey all targeting options for that survey are ignored (e.g. rate limiting, targeting user properties), the only thing you need to do is trigger the event that your survey is targeting and it will show up.

• In the "Preview & Publish" tab select 'React Native' and copy the preview code.
• Implement into your application, this can be done once in any component that's rendered before the event you're targeting

useEffect(() => {
  Iterate.preview('your-survey-id');
}, []);

Recommendations

When implementing Iterate for the first time, we encourage you to implement events for all of your core use cases which you may want to target surveys to in the future. e.g. sign up, purchased, viewed X screen, tapped notification, etc. This way you can easily launch new surveys targeting these events without needing to instrument a new event each time.

Custom fonts

Custom fonts that are available in your app bundle can be used in the Iterate survey view by passing both the filenames (from your assets/fonts folder) and the fonts' postscript names to the Iterate.shared.configure method, like this:

    Iterate.init({
      apiKey: apiKey,
      safeArea: useSafeAreaInsets,
      storage: SecureStorage,
      buttonFont: {
        filename: 'WorkSans-Regular.ttf',
        postscriptName: 'WorkSans-Regular',
      },
      surveyTextFont: {
        filename: 'Merriweather-Regular.ttf',
        postscriptName: 'Merriweather-Regular',
      },
    });

The font specified in the buttonFont parameter will be used in all survey interface buttons (question responses, previous / next buttons, etc). The font specified in surveyTextFont will be used for all other survey text (question prompts, explanatory copy, etc).

True Type fonts and Open Type Fonts are supported.

Associating data with a user

Using the identify method, you can easily add 'user properties' to a user that can be used to target surveys to them and associate the information with all of their future responses. We recommend setting the external_id (needs to be a string) which represents your internal id for the user, this allows us to associate this user across multiple platforms and sessions'

useEffect(() => {
  Iterate.identify({
    email: '[e-mail]',
    external_id: '12abc34',
    is_subscriber: true,
    joined: new Date(),
  });
}, []);

You can also associate 'response properties' with the user's responses to a specific survey (not associated with any future surveys they fill out), by passing an object to the sendEvent method.

useEffect(() => {
  Iterate.sendEvent('viewed-activity-feed', {
    selected_product_id: 12345,
    timestamp: 140002658477
  });
}, []);

For more information see our help article.

Event callbacks

If you need access to the user's responses on the client, you can use the onResponse method to pass a callback function that will return the question and response

useEffect(() => {
  Iterate.onResponse((response, question, survey) => {
    // Your logic here
  });
}, []);

If you need access to other events on the survey (dismiss, survey-complete, etc), you can use the onEvent method to pass a callback function that will fire with each of the events listed below

useEffect(() => {
  Iterate.onEvent((event, data) => {
    // Your logic here
  });
}, []);

Event	Data	Notes
'dismiss'	{ source: 'prompt' | 'survey', progress?: { completed: number, total: number, currentQuestion?: Question; }, survey: Survey }	Progress contains data about how far the user was in the survey when they dismissed. completed is number of questions they've completed (regardless of if they responded to the question or skipped it). total is the total number of questions in the survey. currentQuestion is the question they were on when they dismissed the survey.
'displayed'	{ source: 'prompt' | 'survey', survey: Survey }
'response'	{ response: Response, question: Question, survey: Survey }
'survey-complete'	{ survey: Survey }	Called once when the user reaches the 'thank you' screen

Clearing data

To clear all data Iterate has stored (user api key, any user properties stored by calling the identify method, etc) call the reset method. This is commonly called when you log a user out of your app.

const logout = useCallback(() => {
  Iterate.reset()

  // Your other logout logic here
}, []);

Supporting Markdown in the prompt

To support Markdown in the prompt, you'll need to provide a Markdown renderer. We recommend you use react-native-markdown-display, however you can provide your own component that is an React.ElementType and accepts the markdown string as it's children.

import Markdown from 'react-native-markdown-display';

 Iterate.init({
    apiKey: apiKey,
    safeArea: useSafeAreaInsets,
    storage: SecureStorage,
    markdown: Markdown
  });

Survey eligibility and frequency

By default surveys are only shown once per person and user's can only see at most 1 survey every 72 hours (which is configurable). You can learn more about how eligibility and frequency works.

Troubleshooting

If you have any issues you can head over to our help center to search for an answer or chat with our support team.

Changelog

2.7.2

Released on 2025-04-11.

Fixed

Ampersand's are correctly encoded when present in response properties