Flutter SDK

Survey library to monetize your mobile app, provided by inBrain.ai

Requirements

• Flutter >= 3.13.9

iOS specific requirenments:

• Xcode 14+
• iOS 12.0+ / Catalyst(macOS 10.15.1+), iOS 13.1+
• Swift 5.0+

Android specific requirenments:

• System WebView >= 51.0.2704.90 (default for Android 7.0).

Installation

There are two different options to install inbrain_surveys package:

Add dependency using pubspec.yaml

• Open the pubspec.yaml file located inside the app folder, and add inbrain_surveys: under dependencies;
• Install the new dependency using one of the following options:
  • From Terminal within the project folder run flutter pub get;
  • From VS Code: Click Get Packages located in right side of the action ribbon at the top of pubspec.yaml indicated by the Download icon;
  • From Android Studio/IntelliJ: Click Pub get in the action ribbon at the top of pubspec.yaml.

Add dependency using flutter pub add

• From Terminal within the project folder run flutter pub add inbrain_surveys
• Issue the command while being inside the project directory flutter pub add inbrain_surveys.

Usage

• To start using the package - please, add the corresponding import statement in your code:

  import 'package:inbrain_surveys/inbrain_surveys.dart';
  import 'package:inbrain_surveys/types/types.dart';
• Stop and restart the app (Hot reload and hot restart only update the Dart code, so a full restart of the app might be required to avoid errors like MissingPluginException when using the package).

For a fully functional example, please refer to the sample app which can be found in the plugin folder.

Get Started

Initialize the SDK

void setInbrain({required String apiClientId, required String clientSecret, String? userId});

• apiClientId: The client ID obtained from your Publisher Dashboard
• clientSecret: The client secret obtained from your Publisher Dashboard
• userId: [Optional] The string value that uniquely identifies each user within your application (Example: an email, a username). The value may be provided later using InbrainSurveys.setUserID(String userID) function. This value is provided via S2S Callbacks as PanelistId. See more here: S2S Docs.

Note: This method must be called prior calling all the other methods.

Initialization Example

InbrainSurveys.setInbrain(apiClientId, clientSecret, userId);

User identifier

Set uniq identifier of the user within your application. If value not set (or empty) - deviceId will be used instead. This value is provided via S2S Callbacks as PanelistId. See more here: S2S Docs.

void setUserID(String userId);

• userID: The string value that uniquely identifies each user within your application (Example: an email, a username).

Example

InbrainSurveys.setUserID(userID);

Option #1: Use The Survey Wall

Simply show the survey wall and let the inBrain system handle everything else! Be sure to Setup your S2S Callbacks and fully configure your application here: Publisher Dashboard

Future showSurveys();

Survey Wall Example

InbrainSurveys().areSurveysAvailable().then((available) {
      if (available) {
        InbrainSurveys().showSurveys();
      } else {
        // Show message to the user that there is no available surveys at the moment
      }
    }).catchError((error) {
      // Check the error details and fix it.
    });

Option #2: Use Native Surveys

Native Surveys is similar to an API that can be used within our SDK. Fetch "Surveys" and receive a list of the top surveys for a single user based on their profiler data. inBrain handles collecting profiler data and matching users with the ideal surveys. When fetching surveys, we return a list with details about each survey opportunity such as Reward, Length of Interview, Rating, etc. You are responsible for displaying a representation (button, tile, etc.) for each survey natively within your app.

Future<List<InBrainSurvey>> getNativeSurveys(InBrainFilter filter)

• filter: Optional parameter for filter surveys. Possible options:
  • placementId (String): an optional placement identifier. These can be setup in your Publisher Dashboard
  • categoryIds (List<InBrainCategory>): an optional list of categories. Providing one or more category Ids will limit surveys to those categories.
  • excludedCategoryIds (List<InBrainCategory>): an optional list of EXCLUDED categories. Providing one or more excluded category Ids will only return surveys that do NOT belong to these categories.

Usage

InBrainFilter filter = const InBrainFilter(
    placementId: `placementId`,
    categoryIds: [InBrainCategory.automotive],
    excludedCategoryIds: [InBrainCategory.childrenAndParenting]);

InbrainSurveys().getNativeSurveys(filter)
    .then((List<InBrainSurvey> surveys) {
      // Show the received surveys to the user
    }).catchError((error) {
      // Handle the error
    });
  }

Open A Native Survey

When a user within your app selects a survey, you will then need to call showNativeSurvey along with the following survey data points. This will open the survey within a webview over your app.

Future showNativeSurvey(String searchId, String id)

• searchId: survey's searchId.
• id: id of the surveys to be shown;

Example

  InbrainSurveys().showNativeSurvey(survey.searchId, survey.id);

Understanding Native Surveys

As mentioned in the previous sections, fetching surveys via getNativeSurveys returns an array of survey objects. Below are details related to the properties available with each survey:

Property	Description
id	Id of the survey and the value that should be used when passing parameter to showNativeSurvey()
rank	A normalized value of 1-N where 1 is highest ranked survey and N is the lowest ranked survey
time	An estimation of how many minutes will be required for the user to complete the survey
value	Reward the user will earn by completing the survey. This value is in the currency type (points, coins, cents) you specified within the publisher dashboard and already takes into consideration the revenue share you've allocated to share with the user for a survey completion.
isProfilerSurvey	Boolean value indicating whether the survey represents an inBrain Profiler survey
currencySale	Boolean value indicating if the value of the survey is adjusted based on an active currency sale
multiplier	The currency sale multiplier value applied to the survey value
conversionLevel	Value that indicates the approximate conversion rate of the survey. See possible values here
categories	Array of values indicating what categories this survey belongs to. See possible values here
searchId	This value should be used when opening a native survey. It includes important encoded information related to placement and category filters

Additional Functionality

Add custom tracking data

Set the value to track each user session. This value is provided via S2S Callbacks as SessionId. See more here: S2S Docs

void setSessionID(String sessionId)

• sessionId: Identifier of the session

Example

InbrainSurveys.setSessionID(`session_identifier`)

Customize Navigation Bar

Setup Navigation Bar to match your application style

void setNavigationBarConfig(InBrainNavbarConfig navigationBarConfig);

• navigationBarConfig: the Navigation Bar configuration

Example

InbrainSurveys.setNavigationBarConfig(const InBrainNavbarConfig(
  backgroundColor: Colors.red,
  buttonsColor: Colors.pink,
  titleColor: Colors.blue,
  title: 'inBrain.ai Surveys',
  hasShadow: false,
));

Customize Status Bar

Setup Status Bar to match your application style

 void setStatusBarConfig(InBrainStatusBarConfig statusBarConfig);

• statusBarConfig: the Status Bar configuration

Example

InbrainSurveys.setStatusBarConfig(const InBrainStatusBarConfig(
  lightStatusBar: true, 
  statusBarColor: Colors.orange
));

Check if Surveys are available (Survey Wall Only)

A method to check if the user has surveys available. This is useful to check prior to giving the user an option to open the inBrain Survey Wall. DO NOT use this method when working with Native Surveys, as that does not take into account placement and categories filter options.

Future<bool> areSurveysAvailable();

Example

InbrainSurveys.areSurveysAvailable().then((bool available) {
  print(available);
});

Callbacks

On webview dismissed. If you are using Native Surveys - please, ensure the surveys reloaded each time the webview closed.

Future<void> setOnSurveysClosedListener(InBrainOnCloseHandler handler)

• handler: called after WebView closed by the user. Available OnCloseSurveysData fields:
  • byWebView (boolean): true - webview closed by command from WebPage; false - webview closed by user;
  • rewards? (InBrainSurveyReward[]) - optional list of completed surveys and earned rewards:

    * `surveyId (String surveyId)` - identifier of completed survey;
    * `userReward (num userReward)` - amount of IAC, earned by the user;
    * `outcomeType (InBrainOutcomeType outcomeType)` - type of survey completion (completed or terminated);
    * `placementId ( String? placementId)` - an optional placement identifier of the survey;
    * `categories (List<InBrainCategory>? categories)` - an optional list of the survey's categories.
    NOTE: At the moment only first Native Survey reward is delivered. That means if the user complete a Native Survey, proceed to Survey Wall and complete one more survey - only first reward will be delivered. In case of Survey Wall usage only - no rewards will be delivered.

Usage

InbrainSurveys.setOnSurveysClosedListener(
  (bool closedByWebView, List<InBrainNativeReward>? rewards) {
    print(rewards);
  }
);

Available types:

• InBrainReward: response from .getRewards();
• InBrainNativeSurvey: response from .getNativeSurveys();
• InBrainConversionLevel: InBrainNativeSurvey's field, describes the estimated conversion performance range;
• InBrainFilter: type for filtering data used with .getNativeSurveys();
• InBrainCategory: a full list of available categories;
• InBrainNativeReward: information about completed survey and earned reward;
• InBrainOutcomeType: type of survey completion (completed or terminated);
• InBrainNavbarConfig: Navigation Bar configuration options;
• InBrainStatusBarConfig: Status Bar configuration options.

Full list of categories:

• Automotive
• Beverages Alcoholic
• Beverages Non Alcoholic
• Business
• Children & Parenting
• Coalition Loyalty Programs
• Destinations & Tourism
• Education
• Electronics, Computer Software
• Entertainment And Leisure
• Finance, Banking, Investing & Insurance
• Food
• Gambling, Lottery
• Government & Politics
• HealthCare
• Home
• Media & Publishing
• Personal Care
• Restaurants
• Sensitive & Explicit Content
• Smoking & Tobacco
• Social Research
• Sports Recreation Fitness
• Telecommunications
• Transportation
• Travel - Airlines
• Travel - Hotels
• Travel - Services, Agency, Booking
• Credit Cards
• Video Games
• Fashion & Clothing - Other
• Fashion & Clothing - Department Store

List of available "Conversion Level" values:

Note: The Conversion Level buckets indicate how the survey has been performing platform-wide at inBrain, not necessarily how well the survey will perform for the user its shown to. Its recommended to use these tags only to portray a unique UI.

• New Survey;
• Very Poor Conversion
• Poor Conversion;
• Fair Conversion;
• Good Conversion;
• Very Good Conversion;
• Excellent Conversion.

Troubleshoots