search

andre-paraense / launchdarkly_flutter

A LaunchDarkly Flutter SDK
GNU Lesser General Public License v3.0
4 stars 5 forks source link

readme

LaunchDarkly Client-side SDK for Flutter

codecov License: MIT Pub

This is a LaunchDarkly SDK for Flutter.

This is a work in progress and there are still some features that have not been addressed. You are welcome to contribute.

Getting started

Check LaunchDarkly's documentation for in-depth instructions on configuring and using LaunchDarkly.

To use this plugin, add launchdarkly_flutter as a dependency in your pubspec.yaml file.

Import package:launchdarkly_flutter/launchdarkly_flutter.dart, instantiate LaunchdarklyFlutter and initiate the plugin with your mobile key from your Environments page.

Android integration

Because LaunchDarkly Android's SDK (com.launchdarkly:launchdarkly-android-client-sdk:3.0.0) has the label attribute value set in its <application> element, there is a need to override it with your app's own label, if there is one (you will likely have one! :)). Hence, you will need to add tools:replace="android:label" to the <application> element in your AndroidManifest.xml.

<application
        tools:replace="android:label"
        android:name="io.flutter.app.FlutterApplication"
        android:label="YOUR_LABEL"
        android:icon="@mipmap/ic_launcher">

You will probably need to insert the tools namespace as well, on the top of your AndroidManifest.xml file:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="YOUR.PACKAGE.HERE">

Example

There is an example app that demonstrates how to use the plugin.

You need to instantiate the class and initiate the plugin with your mobile key and the user information, before checking the flags.

// Platform messages are asynchronous, so we initialize in an async method.
LaunchdarklyFlutter launchdarklyFlutter = LaunchdarklyFlutter();

try {
  await launchdarklyFlutter.init('YOUR_MOBILE_KEY', 'USER_ID');
} on PlatformException {}

Be sure to use a mobile key from your Environments page. Never embed a server-side SDK key into a mobile application. Check LaunchDarkly's documentation for in-depth instructions on configuring and using LaunchDarkly.

Optionally, you can choose to pass additional configuration parameters like:

await launchdarklyFlutter.init('YOUR_MOBILE_KEY', 'USER_ID', config: LaunchDarklyConfig(allAttributesPrivate: false,));

Give some time for the initialization process to fetch new flags values (or risk getting the defaults right away), and check them:

// Platform messages are asynchronous, so we fetch flags in an async method.
bool shouldShowButton;
// Platform messages may fail, so we use a try/catch PlatformException.
try {
  shouldShowButton = await launchdarklyFlutter.boolVariation('FLAG_KEY', false);
} on PlatformException {
  shouldShowButton = false;
}

Built-in user attributes

LaunchDarkly includes a set of built-in attributes for users, like key, firstName, lastName, email. For details, please refer to Understanding user attributes.

The built-in user attributes can be set via parameter user of LaunchDarklyUser type:

final user = LaunchDarklyUser(
  email: 'example@example.com',
);
await launchdarklyFlutter.init(mobileKey, userId, user: user);

Custom attributes

In addtion to the built-in user attributes, you can pass your own custom attributes.

final attrs = {
  'string': 'value',
  'boolean': true,
  'number': 10,
};
await launchdarklyFlutter.init(mobileKey, userId, custom: attrs);

Your custom attributes map should have keys of type String and values of type String | bool | number (for deleting an attribute remove the key or set value to null).

Private attributes

You may not want to send all attributes back to LaunchDarkly due to the security or data protection requirements of your organization. LaunchDarkly's private user attributes feature lets you choose which attributes get sent back to LaunchDarkly without sacrificing the ability to target user segments.

final user = LaunchDarklyUser(
  privateEmail: 'example@example.com',
);
final privateAttrs = {
  'string': 'value',
  'boolean': true,
  'number': 10,
};
await launchdarklyFlutter.init(mobileKey, userId, user: user, privateCustom: privateAttrs);

More about private user attributes can be found here.

Changing the User Context

If your app is used by multiple users on a single device, you may want to change users and have separate flag settings for each user.

You can use the identify method to switch user contexts:

await launchdarklyFlutter.identify(userId, user: user, custom: custom, privateCustom: privateCustom);

Not supported yet

Check LaunchDarkly's documentation for more information on the features not yet supported. We are slowly and iteratively adding more features as we use them in our own projects. You are welcome to contribute.

Contributing

We encourage pull requests and other contributions from the community. Check out our contributing guidelines for instructions on how to contribute to this SDK.

About LaunchDarkly