> For the complete documentation index, see [llms.txt](https://help.branch.io/llms.txt).

# Flutter SDK Full Reference

> Full reference for the Branch Flutter SDK, covering every method, parameter, and return value available to your app.

> **Note: Branch data retention policy**
>
> Before sending data to Branch, review the "[Data Branch Hashes](https://help.branch.io/account-hub/best-practices-to-minimize-data-sent-to-branch.md#data-branch-hashes)" section of our data best practices guide for field definitions and retention policies.

## initSession (Deprecated)

| Method | Description |
| --- | --- |
| [Stream<Map<dynamic, dynamic>> initSession()](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L46) | Initiates a session with the Branch API through a listener. |

#### Example Usage

```dart
streamSubscription = FlutterBranchSdk.initSession().listen((data) {
  print('listenDynamicLinks - DeepLink Data: $data');
  controllerData.sink.add((data.toString()));
  if (data.containsKey('+clicked_branch_link') &&
      data['+clicked_branch_link'] == true) {
    print(
      '------------------------------------Link clicked----------------------------------------------');
    print('Custom string: ${data['custom_string']}');
    print('Custom number: ${data['custom_number']}');
    print('Custom bool: ${data['custom_bool']}');
    print('Custom list number: ${data['custom_list_number']}');
    print(
      '------------------------------------------------------------------------------------------------');
    showSnackBar(
      context: context,
      message: 'Link clicked: Custom string - ${data['custom_string']}',
      duration: 10);
  }
}, onError: (error) {
  PlatformException platformException = error as PlatformException;
  print(
    'InitSession error: ${platformException.code} - ${platformException.message}');
  controllerInitSession.add(
    'InitSession error: ${platformException.code} - ${platformException.message}');
});
```

---

## validateSDKIntegration

| Method | Description |
| --- | --- |
| [void validateSDKIntegration()](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L57) | Use the SDK integration validator to check that you've added the Branch SDK and handle deep links correctly when you first integrate Branch into your app. Validates the following: • Branch Keys <br>• Package Name <br>• URI Schemes <br>• Android App Link <br>• Universal Links <br>• Link Domains |

#### Example Usage:

```dart
FlutterBranchSdk.validateSDKIntegration();
```

---

## setRequestMetadata

| Method | Description |
| --- | --- |
| [void setRequestMetadata(String key, String value)](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L19) | Set specific key/value pairs to all requests. This is required for integrating with specific partners like Adobe Analytics, Amplitude, etc. Partner keys can be found in the partner-specific guides. |

| Argument | Type | Description |
| --- | --- | --- |
| `key` | `String` | The partner key. Ex. `$marketing_cloud_visitor_id` |
| `value` | `String` | The value of the partner key |

#### Example Usage

```dart
FlutterBranchSdk.setRequestMetadata(requestMetadataKey, requestMetadataValue);
```

---

## setIdentity

| Method | Description |
| --- | --- |
| [void setIdentity(String userId)](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L14) | Set the identity of a user (ID, UUID, etc.) for events, deep links, and referrals. Use this method when the user logs into their account in your app. See [PII Best Practices](https://help.branch.io/account-hub/best-practices-to-minimize-data-sent-to-branch.md#developer-identity) for details. |

| Argument | Type | Description |
| --- | --- | --- |
| `userId` | `String` | The unique ID of the user |

#### Example Usage

```dart
FlutterBranchSdk.setIdentity('user1234567890');
```

---

## isUserIdentified

| Method | Description |
| --- | --- |
| [Future&lt;bool> isUserIdentified()](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L125) | Indicate whether or not this user has a custom identity specified for them. Note that this is independent of installs. If you call the `setIdentity` method, this device will have that identity associated with this user until the `logout` method is called. This includes persisting through uninstalls, as device ID is tracked. |

#### Example Usage

```dart
bool isUserIdentified = await FlutterBranchSdk.isUserIdentified();
```

## logout

| Method | Description |
| --- | --- |
| [void logout()](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L24) | Clear the identity set from the `setIdentity()` method. This method should be called if you know that the user is explicitly logging out or if a different person is about to use the app. |

#### Example Usage

```dart
FlutterBranchSdk.logout();
```

---

## handleDeepLink

| Method | Description |
| --- | --- |
| [void handleDeepLink(String url)](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L217) | End the current deep link session and starts a new session with the provided URL.<br>To handle push notifications, call this method inside of the push notification callback. |

| Argument | Type | Description |
| --- | --- | --- |
| `url` | `String` | The URL of the deep link for the new session. |

#### Example Usage

```dart
FlutterBranchSdk.handleDeepLink('myapp://open?link_click_id=12345');
```

---

## getLatestReferringParams

| Method | Description |
| --- | --- |
| [Future&lt;Map&lt;dynamic, dynamic>> getLatestReferringParams()](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L29) | Return the last parameters associated with the link that referred the user to the current app session. |

#### Example Usage

```dart
Map<dynamic, dynamic> params = await FlutterBranchSdk.getLatestReferringParams();
```

---

## getFirstReferringParams

| Method | Description |
| --- | --- |
| [Future&lt;Map&lt;dynamic, dynamic>> getFirstReferringParams()](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L34) | Return the first parameters associated with the link that referred the user. Consider this as the parameters used to retrieve the details from the user's first app session. |

#### Example Usage

```dart
Map<dynamic, dynamic> params = await FlutterBranchSdk.getFirstReferringParams();
```

---

## disableTracking

| Method | Description |
| --- | --- |
| [void disableTracking(bool value)](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L40) | If you need to comply with a user's request to not be tracked for GDPR purposes, or otherwise determine that a user should not be tracked, utilize this method to prevent Branch from sending network requests. This setting can also be enabled across all users for a particular link or across your Branch Links. |

| Argument | Type | Description |
| --- | --- | --- |
| `value` | `Boolean` | If set to `true`, `disableTracking` is enabled.<br> If set to `false`, `disableTracking` is disabled. |

#### Example Usage

```dart
FlutterBranchSdk.disableTracking(true);
```

---

## getShortUrl

| Method | Description |
| --- | --- |
| [Future&lt;BranchResponse> getShortUrl( {required BranchUniversalObject buo, required BranchLinkProperties linkProperties})](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L62) | Generate a [Branch Short Link](https://help.branch.io/marketer-hub/deep-link-reference.md#short-links) used for deep linking and attribution. |

| Argument | Type | Description |
| --- | --- | --- |
| `buo` | `BranchUniversalObject` | The [Universal Object](https://help.branch.io/developer-hub/create-branch-objects-and-events.md#branch-universal-object) used to define content within your app. [BUO Best Practices](https://help.branch.io/developer-hub/create-branch-objects-and-events.md#buo-best-practices) |
| `linkProperties` | `BranchLinkProperties` | The analytics properties associated with the link you are about to generate. |

#### Example Usage

```dart
BranchUniversalObject buo = BranchUniversalObject(
  canonicalIdentifier: 'flutter/branch',
  //canonicalUrl: '',
  title: 'Flutter Branch Plugin',
  imageUrl: 'https://flutter.dev/assets/flutter-lockup-4cb0ee072ab312e59784d9fbf4fb7ad42688a7fdaea1270ccf6bbf4f34b7e03f.svg',
  contentDescription: 'Flutter Branch Description',
  keywords: ['Plugin', 'Branch', 'Flutter'],
  publiclyIndex: true,
  locallyIndex: true,
  contentMetadata: BranchContentMetaData()..addCustomMetadata('custom_string', 'abc')
  ..addCustomMetadata('custom_number', 12345)
  ..addCustomMetadata('custom_bool', true)
  ..addCustomMetadata('custom_list_number', [1,2,3,4,5 ])
  ..addCustomMetadata('custom_list_string', ['a', 'b', 'c']),
);

BranchLinkProperties lp = BranchLinkProperties(
  //alias: 'flutterplugin', //define link url,
  channel: 'facebook',
  feature: 'sharing',
  stage: 'new share',
  tags: ['one', 'two', 'three']
);
lp.addControlParam('url', 'http://www.google.com');
lp.addControlParam('url2', 'http://flutter.dev');

BranchResponse response =
  await FlutterBranchSdk.getShortUrl(buo: buo, linkProperties: lp);
if (response.success) {
  print('Link generated: ${response.result}');
} else {
  print('Error : ${response.errorCode} - ${response.errorMessage}');
}
```

---

## showShareSheet

| Method | Description |
| --- | --- |
| [Future&lt;BranchResponse> showShareSheet( {required BranchUniversalObject buo, required BranchLinkProperties linkProperties, required String messageText, String androidMessageTitle = '', String androidSharingTitle = ''})](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L70) | Display a share sheet to prompt the user to share to an external platform (ex. messaging). |

| Argument | Type | Description |
| --- | --- | --- |
| `buo` | `BranchUniversalObject` | The [Universal Object](https://help.branch.io/developer-hub/create-branch-objects-and-events.md#branch-universal-object) used to define content within your app. [BUO Best Practices](https://help.branch.io/developer-hub/create-branch-objects-and-events.md#buo-best-practices) |
| `linkProperties` | `BranchLinkProperties` | The analytics properties associated with the link you are about to generate. |
| `messageText` | `String` | The body of the message in your share sheet. |
| `androidMessageTitle` | `String` | The message title of the share sheet. |
| `androidSharingTitle` | `String` | The sharing title of the share sheet. |

#### Example Usage

```dart
BranchResponse response = await FlutterBranchSdk.showShareSheet(
  buo: buo,
  linkProperties: lp,
  messageText: 'My Share text',
  androidMessageTitle: 'My Message Title',
  androidSharingTitle: 'My Share with');

if (response.success) {
  print('showShareSheet Sucess');
} else {
  print('Error : ${response.errorCode} - ${response.errorMessage}');
}
```

---

## getQRCode

| Method | Description |
| --- | --- |
| [Future&lt;BranchResponse> getQRCodeAsData( {required BranchUniversalObject buo, required BranchLinkProperties linkProperties, required BranchQrCode qrCode})](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L184) | Method `getQRCodeAsData` returns the QR code as Uint8List. Can be stored in a file or converted to image. |
| [Future&lt;BranchResponse> getQRCodeAsImage( {required BranchUniversalObject buo, required BranchLinkProperties linkProperties, required BranchQrCode qrCode})](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L193) | Method `getQRCodeAsImage` returns the QR code as an Image. |

| Argument | Type | Description |
| --- | --- | --- |
| `primaryColor` | `Color` | Color name or Hex color value |
| `backgroundColor` | `Color` | Color name or Hex color value of the background of the QR code itself. |
| `margin` | `Integer (Pixels)` | The number of pixels you want for the margin. Min 1px. Max 20px. |
| `width` | `Integer (Pixels)` | Output size of QR Code image. Min 300px. Max 2000px. (Only applicable to JPEG/PNG) |
| `imageFormat` | `BranchImageFormat` | JPEG, PNG |
| `centerLogoUrl` | `String (HTTP URL)` | URL to the image you want as a center logo e.g. [branch-logo-qrcode.jpeg](https://help.branch.io/files/branch-logo-qrcode.jpeg) |

#### Example Usage

```dart
BranchResponse responseQrCodeImage = await FlutterBranchSdk.getQRCodeAsImage(
  buo: buo!,
  linkProperties: lp,
  qrCode: BranchQrCode(primaryColor: Colors.black, 
                       //primaryColor: const Color(0xff443a49), //Hex colors
                       centerLogoUrl: imageURL,
                       backgroundColor: Colors.white,
                       imageFormat: BranchImageFormat.PNG));

  if (responseQrCodeImage.success) {
      print('QrCode Success');
      showQrCode(this.context, responseQrCodeImage.result);
      /*
       Image(image: responseQrCodeImage.result,
             height: 250,
             width: 250,),
      */
  } else {
     print('Error : ${responseQrCodeImage.errorCode} - ${responseQrCodeImage.errorMessage}');
  }
```

## trackContent

By default, the Branch SDK tracks clicks, opens, installs, reinstalls, and impressions automatically (out-of-the-box).

#### General Event Tracking

Please refer to our [Event Tracking Docs](https://help.branch.io/developer-hub/track-branch-events.md) for more information and examples:

- [Track Commerce Events](https://help.branch.io/developer-hub/track-branch-events.md#track-commerce-events)
- [Track Content Events](https://help.branch.io/developer-hub/track-branch-events.md#track-content-events)
- [Track Lifecycle Events](https://help.branch.io/developer-hub/track-branch-events.md#track-lifecycle-events)
- [Track Custom Events](https://help.branch.io/developer-hub/track-branch-events.md#track-custom-events)

#### Tracking In-App Web View Events

With the Branch Flutter SDK, it is possible to inject JavaScript into an in-app web view with event listeners to make calls to one of our mobile SDKs.

In this scenario, the website’s JavaScript posts a message when a button or element on the page is clicked. The app then uses a JavaScript channel to listen for that message. Inside of the callback, a switch statement is used to check the message and trigger a Branch Event.

To implement this approach:

1. Add JavaScript code to the website to add a listener to the button’s selector and call the `postMessage()` function:

   ```javascript
   var _selector = document.querySelector('button[id=BUTTON_ID]');
   _selector.addEventListener('click', function(event) {
     var message = "LOGIN";

     if (messageHandler) {
       messageHandler.postMessage(message);
     }
   });
   ```
2. Add a JavaScript channel to the WebViewController to handle the `onMessageRecieved` callback and trigger the corresponding Branch Event:

   ```dart
   class _MyWebViewState extends State<MyWebView> {
     late final WebViewController controller;

     @override
     void initState() {
       super.initState();
       controller = WebViewController()
         ..loadRequest(
           Uri.parse('https://your_website.com'),
         );
       controller.setJavaScriptMode(JavaScriptMode.unrestricted);
       controller.addJavaScriptChannel('messageHandler', onMessageReceived: (message) {
         switch (message.message) {
           case "LOGIN":
             BranchEvent event = BranchEvent.standardEvent(BranchStandardEvent.LOGIN);
             FlutterBranchSdk.trackContentWithoutBuo(branchEvent: event);
             break;
           case "PURCHASE":
             BranchEvent event = BranchEvent.standardEvent(BranchStandardEvent.PURCHASE);
             FlutterBranchSdk.trackContentWithoutBuo(branchEvent: event);
             break;
         }
       });
     }
   }
   ```

## registerView

| Method | Description |
| --- | --- |
| [void registerView({required BranchUniversalObject buo})](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L99) | Mark the content referred to by this object as viewed. This will increment the view count of the contents referred by this object. |

| Argument | Type | Description |
| --- | --- | --- |
| `buo` | `BranchUniversalObject` | The [Universal Object](https://help.branch.io/developer-hub/create-branch-objects-and-events.md#branch-universal-object) used to define content within your app. [BUO Best Practices](https://help.branch.io/developer-hub/create-branch-objects-and-events.md#buo-best-practices) |

#### Example Usage

```dart
FlutterBranchSdk.registerView(buo: buo);
```

---

## listOnSearch

| Method | Description |
| --- | --- |
| [Future&lt;bool> listOnSearch( {required BranchUniversalObject buo, BranchLinkProperties? linkProperties})](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L105) | On iOS, list items on Spotlight. |

| Argument | Type | Description |
| --- | --- | --- |
| `buo` | `BranchUniversalObject` | The [Universal Object](https://help.branch.io/developer-hub/create-branch-objects-and-events.md#branch-universal-object) used to define content within your app. [BUO Best Practices](https://help.branch.io/developer-hub/create-branch-objects-and-events.md#buo-best-practices) |
| `linkProperties` | `BranchLinkProperties` | The analytics properties associated with the link you are about to generate. |

#### Example Usage

```dart
bool success = await FlutterBranchSdk.listOnSearch(buo: buo);
print(success);
```

---

## removeFromSearch

| Method | Description |
| --- | --- |
| [Future&lt;bool> removeFromSearch( {required BranchUniversalObject buo, BranchLinkProperties? linkProperties})](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L115) | On iOS, remove the BUO from Spotlight if privately indexed. |

| Argument | Type | Description |
| --- | --- | --- |
| `buo` | `BranchUniversalObject` | The [Universal Object](https://help.branch.io/developer-hub/create-branch-objects-and-events.md#branch-universal-object) used to define content within your app. [BUO Best Practices](https://help.branch.io/developer-hub/create-branch-objects-and-events.md#buo-best-practices) |
| `linkProperties` | `BranchLinkProperties` | The analytics properties associated with the link you are about to generate. |

#### Example Usage

```dart
bool success = await FlutterBranchSdk.removeFromSearch(buo: buo);
print('Remove sucess: $success');
```

---

## setIOSSKAdNetworkMaxTime

| Method | Description |
| --- | --- |
| [void setIOSSKAdNetworkMaxTime(int hours)](https://github.com/BranchMetrics/flutter_branch_sdk/blob/master/lib/src/flutter_branch_sdk.dart#L108) | Set the time window for SKAdNetwork callout in hours on **iOS only**.<br>By default, Branch limits calls to SKAdNetwork to within 72 hours after first install. |

| Argument | Type | Description |
| --- | --- | --- |
| `hours` | `int` | Time window in hours. |

#### Example Usage

```dart
FlutterBranchSdk.setIOSSKAdNetworkMaxTime(24);
```

---

## requestTrackingAuthorization

| Method | Description |
| --- | --- |
| [Future&lt;AppTrackingStatus> requestTrackingAuthorization()](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L131) | Request AppTracking Authorization and returns AppTrackingStatus on **iOS only**. |

#### Example Usage

```dart
AppTrackingStatus status = await FlutterBranchSdk.requestTrackingAuthorization();
print(status);
```

---

## getTrackingAuthorizationStatus

| Method | Description |
| --- | --- |
| [Future&lt;AppTrackingStatus> getTrackingAuthorizationStatus()](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L137) | Return AppTrackingStatus on **iOS only**. |

#### Example Usage

```dart
AppTrackingStatus status = await FlutterBranchSdk.getTrackingAuthorizationStatus();
print(status);
```

---

## getAdvertisingIdentifier

| Method | Description |
| --- | --- |
| [Future&lt;String> getAdvertisingIdentifier()](https://github.com/BranchMetrics/flutter_branch_sdk/blob/af43e31020e636e99d47a43dc7016894eb7ed66e/lib/src/flutter_branch_sdk.dart#L143) | Return the advertising identifier on **iOS only**. |

#### Example Usage

```dart
String status = await FlutterBranchSdk.getAdvertisingIdentifier();
print(status);
```