Skip to main content

gleap_sdk 19.4.0 copy "gleap_sdk: ^19.4.0" to clipboard
gleap_sdk: ^19.4.0 copied to clipboard

Gleap SDK for Flutter: customer support, live chat, in-app bug reporting and customer feedback.

Gleap Flutter SDK #

Gleap Flutter SDK Intro

Add AI-native customer support, live chat, in-app bug reporting, a help center and surveys to your Flutter apps with Gleap. Gleap is an Intercom alternative for software teams that connects customer conversations and feedback with product development.

SDK documentation · Website · Plans and pricing

Docs & examples #

Checkout our documentation for full reference. Include the following dependency in your pubspec.yaml:

dependencies:
  gleap_sdk: "^19.0.1"

Inline banners

Inline banners (the banner style set in the Gleap dashboard) cover the top of the app on Android and iOS. To push the app down below them instead, like inline banners on the web, wrap it in GleapBannerArea:

MaterialApp(
  builder: (context, child) => GleapBannerArea(child: child!),
  home: const HomeScreen(),
)

Floating banners still float above the app; Gleap.bannerHeight gives the height for custom layouts.

Flutter v2 support

If you are using Flutter < v3, please import the gleap_sdk as shown below:

dependencies:
  gleap_sdk:
    git:
      url: https://github.com/GleapSDK/Flutter-SDK.git
      ref: flutter-v2

Flutter v2 Support If you are using Flutter < v3, please import the gleap_sdk as shown below:

dependencies:
  gleap_sdk:
    git:
      url: git@github.com:GleapSDK/Flutter-SDK.git
      ref: flutter-v2

Android installation

Android should be already good to go. If theres a version conflict pls add the following to your android manifest:

<manifest ... xmlns:tools="http://schemas.android.com/tools">
 <uses-sdk  android:minSdkVersion="21"
        tools:overrideLibrary="io.gleap.gleap_sdk"/>
 <application .... tools:overrideLibrary="io.gleap.gleap_sdk">
 ...

Important: Always have a look at your minSdkVersion on android and your minimum target version on iOS to keep them on the same minimum version gleap needs.

iOS installation

gleap_sdk needs an iOS deployment target of 15.0 or higher. On iOS it is a Swift package (ios/gleap_sdk/Package.swift) that pulls the native Gleap iOS SDK from GitHub; it still ships a podspec for apps that use CocoaPods. Flutter picks one of the two for you.

Swift Package Manager (recommended). Needs Flutter 3.41 or newer (the plugin's package depends on the FlutterFramework package that Flutter generates since 3.41) and Xcode 15 or newer. From Flutter 3.44 Swift Package Manager is on by default: run flutter run or flutter build ios and Flutter adds the integration to your Xcode project. On Flutter 3.41 to 3.43 turn it on first with flutter config --enable-swift-package-manager, or for the project in your app's pubspec.yaml:

flutter:
  config:
    enable-swift-package-manager: true

Set the Runner target's Minimum Deployments to 15.0 in Xcode, otherwise Xcode reports that gleap-sdk requires iOS 15.0. See Swift Package Manager for app developers for details, including how to remove CocoaPods once all your plugins support Swift Package Manager.

CocoaPods. Used on Flutter older than 3.41 and whenever Swift Package Manager is turned off (on Flutter 3.24 to 3.40 keep it off, which is the default there). Set platform :ios, '15.0' in ios/Podfile and run flutter run / flutter build ios (or pod install in ios/); when upgrading from an older gleap_sdk, run pod update Gleap gleap_sdk in ios/ once. CocoaPods trunk becomes read-only on December 2, 2026, so Gleap iOS SDK versions released after that date are not on trunk. For those, pod install fails with None of your spec sources contain Gleap (= X.Y.Z); add the SDK from GitHub to the Runner target in your Podfile, with the version the plugin requires (s.dependency 'Gleap', 'X.Y.Z' in the plugin's ios/gleap_sdk.podspec):

target 'Runner' do
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
  pod 'Gleap', :git => 'https://github.com/GleapSDK/Gleap-iOS-SDK.git', :tag => '19.0.0'
end

Swift Package Manager is the recommended setup: after December 2, 2026 new Gleap iOS SDK versions are only released through GitHub and Swift Package Manager. Only use that pod 'Gleap' line with CocoaPods: if gleap_sdk comes through Swift Package Manager, a pod 'Gleap' in the Podfile links the Gleap iOS SDK a second time.

Apps that embed Flutter into an existing iOS app (add-to-app) can use either the Swift Package Manager integration (flutter build swift-package, Flutter 3.44+, see Integrate a Flutter app into your iOS project) or the CocoaPods integration with the same Podfile line.

Web installation

Navigate to your web project folder and insert the following snippet as first element within the head tag of your index.html

<script>
!function(Gleap,t,i){if(!(Gleap=window.Gleap=window.Gleap||[]).invoked){for(window.GleapActions=[],Gleap.invoked=!0,Gleap.methods=["identify","updateContact","setEnvironment","setEnvDataPropsToIgnore","setDisableEnvData","setColorScheme","setTags","attachCustomData","setCustomData","removeCustomData","clearCustomData","setTicketAttribute","unsetTicketAttribute","clearTicketAttributes","registerCustomAction","registerAgentTool","trackEvent","log","preFillForm","showSurvey","sendSilentCrashReport","startFeedbackFlow","startClassicForm","startConversation","startBot","setAppBuildNumber","setAppVersionCode","setApiUrl","setFrameUrl","setRegion","setWSApiUrl","setRealtimeHost","setBannerUrl","setModalUrl","startNetworkLogger","setNetworkLogsBlacklist","setNetworkLogPropsToIgnore","setDisableInAppNotifications","isOpened","open","close","on","setLanguage","setOfflineMode","initialize","disableConsoleLogOverwrite","logEvent","hide","enableShortcuts","showFeedbackButton","destroy","getIdentity","isUserIdentified","clearIdentity","openConversations","openConversation","openChecklists","openChecklist","startChecklist","openHelpCenterCollection","openHelpCenterArticle", "askAI","openHelpCenter","searchHelpCenter","openNewsArticle","openNews","openFeatureRequests","isLiveMode"],Gleap.f=function(e){return function(){var t=Array.prototype.slice.call(arguments);window.GleapActions.push({e:e,a:t})}},t=0;t<Gleap.methods.length;t++)Gleap[i=Gleap.methods[t]]=Gleap.f(i);Gleap.load=function(){var t=document.getElementsByTagName("head")[0],i=document.createElement("script");i.type="text/javascript",i.async=!0,i.src="https://sdk.gleap.io/latest/index.js",t.appendChild(i)},Gleap.load()}}();
</script>

Initialize Gleap SDK

Import the Gleap SDK by adding the following import inside one of your root components.

import 'package:gleap_sdk/gleap_sdk.dart';
Gleap.initialize(token: 'YOUR_API_KEY')

Your API key can be found in the project settings within Gleap.

Data regions

Projects hosted in the US data region select it before initializing. The default region is eu, so existing integrations need no change.

await Gleap.setRegion(region: 'us');
await Gleap.initialize(token: 'YOUR_API_KEY');

setRegion sets the API, websocket and realtime hosts for the region at once; the static widget hosts are global and stay unchanged. For custom domains, the manual setters setApiUrl, setWSApiUrl, setRealtimeHost, setFrameUrl, setBannerUrl and setModalUrl are available. A manual setter called after setRegion overrides that single host.

On web, data regions require the loader snippet above (it queues the new methods until the JavaScript SDK has loaded).

Dark mode

Switch the widget between dark and light mode. auto follows the device appearance (on web: the page theme). If your app has its own theme toggle, pass light or dark explicitly and call it again whenever the theme changes:

await Gleap.setColorScheme(colorScheme: 'auto');
await Gleap.setColorScheme(
  colorScheme: Theme.of(context).brightness == Brightness.dark ? 'dark' : 'light',
  darkBackgroundColor: '#121212',
);

setColorScheme only takes effect when "Adapt to dark / light mode" is enabled in the Gleap dashboard; it then overrides the dashboard's color scheme. Before the first call the dashboard setting applies. In dark mode the widget uses the dark mode colors, logo, header image and composer glow set in the Gleap dashboard; without dark colors it keeps its normal colors. lightBackgroundColor / darkBackgroundColor override the background in light / dark mode. Can be called before or after Gleap.initialize.

Customer identity (JWT)

Signed identity (recommended)

Your backend signs an HS256 JWT with an identity key from Settings → Security → Identity keys (put the key id in the kid header; the secret never leaves your server). The userId claim is required. Optional claims: email, name, company ({ id, name }), plan, and provider ids such as stripeCustomerId. Set exp to at most one hour. Everything in the token lands on the contact as signed data the app cannot change. Pass the token to the SDK after login and on every app start of a logged-in user; setUserJwt keeps it in memory only. setUserJwtProvider fetches a fresh token when it expires, and setAuthTokens hands Kai your own API tokens for this user. See Customer identity.

// After login and on every app start of a logged-in user
await Gleap.setUserJwt(token: token);

// Called when the token has expired or is about to; return a fresh one
Gleap.setUserJwtProvider(provider: () async => await myBackend.fetchGleapToken());

// Optional: shorten the signed session (milliseconds)
await Gleap.setSessionDuration(milliseconds: 24 * 60 * 60 * 1000);

// Optional: tokens API tools may use to call your backend as this user (null removes one)
await Gleap.setAuthTokens(tokens: {'backend': accessToken});

setSessionDuration(ms) shortens the signed session; the project's maximum applies.

The identity handling runs in the native iOS and Android SDKs on mobile, so their behaviour applies here as is: setUserJwt may be called before initialize (the token is sent once the SDK starts), a returning user on a project that switched to Signed gets the identify of this app start sent once to obtain a signed session, and a short session duration is renewed at half its lifetime.

Legacy user hash

Instead of a token you can still identify with a user hash: the HMAC-SHA256 of the user id, created on your server with the project's identity verification secret. It is accepted while "Accept legacy user hash" stays on in the project's security settings.

await Gleap.identifyContact(
  userId: 'user-1',
  userProperties: GleapUserProperty(email: 'user@example.com'),
  userHash: userHash,
);

Protected conversation files

With "Require authenticated file access" (Project settings → User identity), conversation files can only be opened by agents and by the verified customer the conversation belongs to. Identify the customer with a signed identity on every app start (Gleap.setUserJwt, or the legacy user hash); guests and contacts identified without a signature cannot open the file.

Email replies link attachments to your customer application URL with a gleapFile query parameter. If that URL opens your app (universal link / App Link, e.g. handled with app_links), pass it to Gleap; the conversation opens once the customer is identified with a signed identity:

final bool isGleapFile = await Gleap.openProtectedFileFromUrl(url: uri.toString());

openProtectedFileFromUrl returns true if the link carries a Gleap file reference and false otherwise. Keep the parameter through your app's login flow. On web the JavaScript SDK opens ?gleapFile= links on page load by itself, so the method returns false there.

Network logging

We support network logging for the packages Http and Dio. For details on how to enable network logging for these packages, check the Gleap Http Interceptor and the Gleap Dio Interceptor packages (2.0 or newer).

Requests from any other client can be logged with Gleap.logNetworkRequest:

Gleap.logNetworkRequest(
  GleapNetworkLog(
    type: 'POST',
    url: 'https://api.example.com/orders',
    date: startedAt, // when the request started
    duration: stopwatch.elapsedMilliseconds.toDouble(),
    success: true, // false when no response arrived
    request: GleapNetworkRequest(
      headers: {'content-type': 'application/json'},
      payload: {'productId': 42}, // Maps and Lists are sent as JSON
    ),
    response: GleapNetworkResponse(
      status: 201,
      statusText: 'Created',
      headers: {'content-type': 'application/json'},
      responseText: responseBody,
      // for a failed request: GleapNetworkResponse(errorText: 'Connection refused')
    ),
  ),
);

Gleap keeps the newest 30 requests. Gleap.setNetworkLogPropsToIgnore(propsToIgnore: ['password', 'token']) removes headers, JSON keys (at any depth, user.password also works as a path), form fields and url query parameters with these names; Gleap.setNetworkLogsBlacklist(blacklist: ['/internal/']) skips requests whose url contains an entry. Authorization and cookie headers are always masked.

Switch network logging on or off from your app, also against the network logs setting in the Gleap dashboard:

await Gleap.stopNetworkLogging();
await Gleap.startNetworkLogging(); // resumes after a stop

Without these calls nothing changes: requests logged from Dart are attached, and the native recording on iOS and web follows the dashboard setting.

  • All platforms: after stopNetworkLogging, logNetworkRequest and attachNetworkLogs (and with them the Gleap http and dio interceptors) ignore new requests until startNetworkLogging is called. Requests logged before stay attached.
  • iOS: the native SDK records every NSURLSession request of the app (e.g. made by native plugins or cupertino_http) when network logs are enabled in the dashboard. startNetworkLogging starts this recording, stopNetworkLogging stops it.
  • Web: startNetworkLogging also starts the JavaScript SDK's network logger (fetch and XMLHttpRequest). The JavaScript SDK can't stop it, so on web stopNetworkLogging only stops the requests logged from Dart.
14
likes
0
points
15k
downloads

Publisher

verified publishergleap.io

Weekly Downloads

Gleap SDK for Flutter: customer support, live chat, in-app bug reporting and customer feedback.

Homepage

License

unknown (license)

Dependencies

flutter, flutter_web_plugins, json_annotation

More

Packages that depend on gleap_sdk

Packages that implement gleap_sdk