DocumentationAPI ReferenceSupport
API Reference
Sign In

Flutter Guide

Create an Account

You can create a free account with us by accessing the signup page.

To create and run A/B tests, sign in to the VWO dashboard and then select Mobile App A/B on the menu. If you are using the VWO A/B testing feature for the first time, click Start Mobile App A/B Testing to begin.

To create A/B tests for mobile apps:

Add the mobile app to be tested.

Define the variables you want to test.

Create A/B tests

Create an App

Registering your app on VWO is a one-time process.
Adding your app generates an Api Key, which is used by VWO servers to recognize your app.

Select the Mobile App A/B option under the test menu.
Click Create, and then click Add App. Write a name for your app, and in the Platform option, select Android.

Note the api key generated by the system.

Add the mobile app to be tested

To add a new app for A/B testing, go to the Apps section on the page.

On the right side of the screen, click Create App.
Type the name of the app you want to add, and then click Create.

As you add an app, VWO generates API Keys for both the iOS and Android platforms. You can make a note of the API Key under the Settings section and are used during app initialization.

Defining the Variables You Want To Test

Test variables are elements or parameters of your mobile app. After you define a variable, you can run an unlimited number of A/B tests on the variable, without doing any code changes or redeployment. For example, you can create a string-type variable for testing different text versions in the app screen.

Under the Apps tab, select the mobile app for which you want to create test variables.

To add an element for testing, under Variables section, click Create Variable.

Assign a name to the variable, and then select its data type.

Type Default Value (current value or a value if there is no A/B test).

To add the variable, click Create. You can add multiple variables to an app.

Creating A/B Tests for Mobile Apps

On the Mobile App A/B testing screen, go to the Campaigns tab, and then click Create.

Choose the App you want to test. All mobile apps you have added to VWO are listed here.

Select a platform where the app is running.

Enter a unique identifier in the Define a test key field to filter your tests easily. The test key helps you execute custom logic, as explained in this iOS Code Blocks/Android Code Blocks section.

Select Next and click Add Variable. All the variables you have created for the test are displayed here. You can choose to Create Variable by adding a new test variable.

Select the variable you want to test, and then enter the variation values. You can test multiple variables in one test. In the example above, we have added speed variable, defined value as 20 for the variation. For control, the value is 10, which is the default value for the variable.

Based on the test key and variation names, VWO generates the code snippet that you can use in the mobile app.

To continue, click Next

Define Goals

In the next step, define at least one goal. The Goal is a conversion matrix that you may want to optimize.

To edit the goal name, click the corresponding Goal icon. In the box below the Goal* icon, select the drop-down menu to select an event that you want to track. Provide the relevant information in the Goal Identifier text box.

To define more goals, select Add Another Goal or select Next.

conversionGoal

Finalize

In the Finalize step, we need to specify the campaign name. Next, we can set the percentage of users that we want to include in the campaign.

Under Integrate With Third-Party Products, select the box corresponding to the product name with which you want to integrate the app.

Under Advanced Options, you can also target the campaign for specific user types, enable scheduling, customize traffic allocation for each variation, or make the user part of the campaign on app launch.

For quick setup, we can leave those settings to default.

Click Finish.

On the next screen, click Start Now to run the campaign.

Installing Library

The library is published in pub.dev. You can check it here.

The library can be installed through pubspec.yaml

vwo_flutter: ^1.0.3

Enable the preview mode

Previews are by default enabled.

Disable the preview mode

Preview mode can be disabled by setting the disablePreview flag to true in your VWOConfig object.

VWOConfig vwoConfig = VWOConfig(disablePreview: true);

🚧

NOTE

While creating a release build of your Flutter App, previews should be disabled.

Code changes

1. Initialising the SDK

After installing the library, you would want to initialize it.
Import the Library as follows:

import 'package:vwo_flutter/vwo_flutter.dart';

Library can be initialized in the following ways:

I. Launching VWO SDK

VWOConfig vwoConfig = VWOConfig(userId:"", optOut: false,  disablePreview: true, customVariables: {}, customDimensionKey: "", customDimensionValue: "");

if (Platform.isIOS) {
  await VWO.launch("YOUR_IOS_API_KEY", vwoConfig: vwoConfig);
} else {
  await VWO.launch("YOUR_ANDROID_API_KEY", vwoConfig: vwoConfig);
}

Launch configuration

You can set up VWO Config while initializing your VWO SDK. Config is VWOConfig object which can have following parameters:

  • userId: You can identify a user in the VWO SDK using a string which identifies that user.

  • optOut: It can have a boolean value that tells the VWO SDK whether to initialize the SDK or not. It defaults to false.

  • disablePreview: Boolean value to turn on or off the preview mode. It defaults to false.

  • customVariables: Takes in a Map as its value. Check Targeting Visitor Groups / Targeting Visitor Groups for more details. It defaults to an empty object.

  • customDimensionKey: String value which is the unique key associated with a particular custom dimension made in the VWO application. Check Push Custom Dimension for more details. It defaults to an empty String.

  • customDimensionValue: String value which is the value you want to tag a custom dimension with. Check Push Custom Dimension for more details. It defaults to an empty String.

VWOConfig vwoConfig = VWOConfig(userId:"", optOut: false,  disablePreview: true, customVariables: {}, customDimensionKey: "", customDimensionValue: "");

You can set this config object as follows:

if (Platform.isIOS) {
  await VWO.launch("YOUR_IOS_API_KEY", vwoConfig: vwoConfig);
} else {
  await VWO.launch("YOUR_ANDROID_API_KEY", vwoConfig: vwoConfig);
}

2. Using campaign

To use the variation defined during campaign creation, use an of the following function to get the value for the campaign keys.

await VWO.getObjectForKey(key, DEFAULT_VALUE)

await VWO.getIntegerForKey("key", 1)

await VWO.getStringForKey("key", "default_value")

await VWO.getDoubleForKey("key", 0.0)

await VWO.getBooleanForKey("key", false)

When these methods are invoked, the SDK checks if the targeting conditions hold true for the current user.
If targeting/segmentation conditions hold true, the user is made part of the campaign and visitor counts in the report section increments by one (once per user).

Test can also be created without variables. Campaign test key can be used to fetch the variation name. This variation name can be used to execute custom logic.

await VWO.getVariationNameForTestKey("campaign_key")

📘

NOTE

Can be called only after SDK initialisation. Otherwise, a null value is returned.

3. Triggering goals

We would track the effect of this campaign on our conversion metric.
Earlier we defined conversionGoal as a goal.
We need to tell the VWO SDK when this conversion happens. Use the following code to trigger this goal.

var goal = "conversionGoal";

await VWO.trackConversion(goal);

For triggering revenue goal use method trackConversion(goal, revenueValue: value).

var goal = "revenueGoal";

await VWO.trackConversion(goal, revenueValue: REVENUE_VALUE);

📘

NOTE

Can be called only after SDK initialisation. Otherwise, the goal is not marked.

4. Push Custom Dimension

Pushes a custom dimension for a particular user to the VWO server. It is used for post-segmenting the data in the campaign reports.

Read here on how to create custom dimension in VWO

The API method accepts a custom dimension key - customDimensionKey and custom dimension value - customDimensionValue.

customDimensionKey is the unique key associated with a particular custom dimension made in VWO application.

customDimensionValue is the value you want to tag a custom dimension with.

await VWO.pushCustomDimension("CUSTOM_DIMENSION_KEY", "CUSTOM_DIMENSION_VALUE");

Logging

To enable logging in SDK, use VWO.setLogLevel(VWOLog.ALL);.
You can set different log levels depending upon the priority of logging as follows:

  • ALL: Gives detailed logs.
  • INFO: Informational logs
  • CONFIG: Debugging logs.
  • WARNING: Warning is a message level indicating a potential problem.
  • SEVERE: Indicates Error
  • OFF: No logs are printed

The different methods set the log level of the message. VWO will only print messages with a log level that is greater to or equal to it's current log level setting. So a logger with a level of Warning will only output log messages with a level of WARNING, or SEVERE.

VWO.setLogLevel(VWOLog.ALL);

📘

See Android Logging for verbose logging in Android SDK.

Opt out

To opt out of tracking by VWO, use VWOConfig object to set OptOut to true or false. This config object is passed when VWO.launch function is called.

VWOConfig vwoConfig = VWOConfig(optOut: true);

await VWO.launch('YOUR_API_KEY', vwoConfig: config)

Integrations

You can send VWO's campaign information to third-party analytics platforms by using Streams. You can then segment the analytics report by using VWO's campaign id, campaign name, variation id, or name.

Stream Listener

The code can listen to a Stream on the VWO instance.

Here is how Stream listeners can be integrated into any dart file.

VWO.vwoStream.listen((vwoProperties) {
      String campaignId = vwoProperties["vwo_campaign_name"];
      String campaignName =  vwoProperties["vwo_campaign_id"];
      String variationId =  vwoProperties["vwo_variation_name"];
      String variationName =  vwoProperties["vwo_variation_id"];
      print("Campaign id $campaignId, Campaign name $campaignName, VariationId $variationId, VariationName $variationName" );
});

Stream Data

On listening to a Stream, you can get the campaign data from the vwoProperties object which is passed to the callback.

The data contains the following keys:

  • vwo_campaign_id : Identifier of the campaign; this is generated by VWO. This is unique for your account.
  • vwo_campaign_name : Name of the campaign, as set by you. This is not necessarily unique.
  • vwo_variation_id : Identifier of the variation in the campaign of which the user became a part. Variation Id is unique for its campaign, but it is not unique across different campaigns.
  • vwo_variation_name : Name of the variation in the campaign, as set by you. This is not necessarily unique.

You can close and open the streams depending upon your needs. 

// use this code to close the stream
VWO.closeVWOStream();

// use this code to open the stream and start listening.
VWO.openVWOStream();

📘

Note

Upon opening a new Stream, always create new listeners as the previous listeners won't listen to the new stream.

Next, you will find suggested implementations for one of the common analytics platforms. Feel free to use these as showcased or adapt them to meet your specific needs.

Mixpanel

VWO.vwoStream.listen((vwoProperties) {
    String campaignId = vwoProperties["vwo_campaign_name"];
    String campaignName =  vwoProperties["vwo_campaign_id"];
    String variationId =  vwoProperties["vwo_variation_name"];
    String variationName =  vwoProperties["vwo_variation_id"];
    print("Campaign id $campaignId, Campaign name $campaignName, VariationId $variationId, VariationName $variationName" );
    

    Mixpanel mixpanel = await Mixpanel.init("Your Mixpanel Token", optOutTrackingDefault: false);
    mixpanel.track('campaign_started', properties: vwoProperties );
});

📘

NOTE

Stream Listeners also allows for flexibility to implement an integration with a platform that is not listed here.

Reports

From the Mobile App A/B menu, select your campaign and click Detailed Reports to see reports of your campaign.

Source Code

The plugin is published on pub.dev: vwo_flutter

VWO Flutter Plugin source code is available on GitHub:
vwo-flutter-sdk

Next Steps

As a next step, take a look at:
Detailed iOS documentation: SDK Reference
Detailed Android documentation: SDK Reference

We would look forward to hear from you about any question or feedback at [email protected].