Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 51 additions & 43 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

⚠️ ⚠️
We are no longer mantaining this library. Feel free to fork it and work on your own branch.
⚠️ ⚠️

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-


# Segment plugin

[![Pub Version](https://img.shields.io/pub/v/flutter_segment)](https://pub.dev/packages/flutter_segment)
[![style: lint](https://img.shields.io/badge/style-lint-4BC0F5.svg)](https://pub.dev/packages/lint)

Expand All @@ -16,35 +8,40 @@ This library was created by our friends at [claimsforce-gmbh](https://github.com
Flutter plugin to support iOS, Android and Web sources at https://segment.com.

### Future development

We want to prepare flutter-segment for the future!
Please have a look at [this issue](https://github.com/claimsforce-gmbh/flutter-segment/issues/46) and let us know what you think.

## Usage

To use this plugin, add `flutter_segment` as a [dependency in your pubspec.yaml file](https://flutter.io/platform-plugins/).

### Important note for iOS usage

Since version `3.5.0` we are forcing all users to use `use_frameworks!` within the [`Podfile`](https://github.com/claimsforce-gmbh/flutter-segment/blob/master/example/ios/Podfile#L31) due to import issues of some 3rd party dependencies.

### Supported methods

| Method | Android | iOS | Web | MacOS | Windows | Linux |
|------------------|---|---|---|---|---|---|
| `identify` | X | X | X | | | |
| `track` | X | X | X | | | |
| `screen` | X | X | X | | | |
| `group` | X | X | X | | | |
| `alias` | X | X | X | | | |
| `getAnonymousId` | X | X | X | | | |
| `reset` | X | X | X | | | |
| `disable` | X | X | | | | |
| `enable` | X | X | | | | |
| `flush` | X | X | | | | |
| `debug` | X* | X | X | | | |
| `setContext` | X | X | | | | |
| ---------------- | ------- | --- | --- | ----- | ------- | ----- |
| `identify` | X | X | X | | | |
| `track` | X | X | X | | | |
| `screen` | X | X | X | | | |
| `group` | X | X | X | | | |
| `alias` | X | X | X | | | |
| `getAnonymousId` | X | X | X | | | |
| `reset` | X | X | X | | | |
| `disable` | X | X | | | | |
| `enable` | X | X | | | | |
| `flush` | X | X | | | | |
| `debug` | X\* | X | X | | | |
| `setContext` | X | X | | | | |

\* Debugging must be set as a configuration parameter in `AndroidManifest.xml` (see below). The official segment library does not offer the debug method for Android.

### Example
``` dart

```dart
import 'package:flutter/material.dart';
import 'package:flutter_segment/flutter_segment.dart';

Expand Down Expand Up @@ -85,25 +82,27 @@ class MyApp extends StatelessWidget {
}
```


## Migration from `v2.x` to `v3.x`

In `v3.x` we removed branch io integration as the package is in the the maintenance mode and uses outdated dependencies.
If you don't use `ENABLE_BRANCH_IO_INTEGRATION` you are good to go.
If you want to continue using `ENABLE_BRANCH_IO_INTEGRATION` then use `v2.x` of this package.

## Installation

Setup your Android, iOS and/or web sources as described at Segment.com and generate your write keys.

Set your Segment write key and change the automatic event tracking (only for Android and iOS) on if you wish the library to take care of it for you.
Remember that the application lifecycle events won't have any special context set for you by the time it is initialized.

### Via Dart Code

```dart
void main() {
/// Wait until the platform channel is properly initialized so we can call
/// `setContext` during the app initialization.
WidgetsFlutterBinding.ensureInitialized();

String writeKey;
if(Platform.isAndroid){
writeKey = "ANDROID_WRITE_KEY";
Expand All @@ -122,7 +121,8 @@ void main() {
}
```

### Android _(Deprecated*)_
### Android _(Deprecated\*)_

```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.flutter_segment_example">
<application>
Expand All @@ -137,7 +137,8 @@ void main() {
</manifest>
```

### iOS _(Deprecated*)_
### iOS _(Deprecated\*)_

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
Expand All @@ -156,27 +157,29 @@ void main() {
```

### Web

```html
<!DOCTYPE html>
<html>
<head>
[...]
</head>
<body>
<script>
!function(){ ...;
analytics.load("YOUR_WRITE_KEY_GOES_HERE");
analytics.page();
}}();
</script>
<script src="main.dart.js" type="application/javascript"></script>
</body>
<head>
[...]
</head>
<body>
<script>
!function(){ ...;
analytics.load("YOUR_WRITE_KEY_GOES_HERE");
analytics.page();
}}();
</script>
<script src="main.dart.js" type="application/javascript"></script>
</body>
</html>

```

For more informations please check: https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/quickstart/

## Sending device tokens strings for push notifications

Segment integrates with 3rd parties that allow sending push notifications.
In order to do that you will need to provide it with the device token string - which can be obtained using one of the several Flutter libraries.

Expand All @@ -199,17 +202,20 @@ await Segment.track(eventName: 'Application Opened');
```

A few important points:

- The token is propagated as-is to Segment through the context field, without any manipulation or intermediate calls to Segment's libraries. Strucutred data - such as APNs - need to be properly converted to its string representation beforehand
- On iOS, once the `device.token` is set, calling `setContext({})` will *not* clean up its value. This occurs due to the existence of another method from segment's library that sets the device token for Apple Push Notification service (APNs )
- On iOS, once the `device.token` is set, calling `setContext({})` will _not_ clean up its value. This occurs due to the existence of another method from segment's library that sets the device token for Apple Push Notification service (APNs )
- `setContext` always overrides any previous values that were set in a previous call to `setContext`
- `setContext` is not persisted after the application is closed

## Setting integration options

If you intend to use any specific integrations with third parties, such as custom Session IDs for Amplitude, you'll need to set it using options for each call, or globally when the application was started.

### Setting the options in every call

The methods below support `options` as parameters:

- `identify({@required userId, Map<String, dynamic> traits, Map<String, dynamic> options})`
- `track({@required String eventName, Map<String, dynamic> properties, Map<String, dynamic> options})`
- `screen({@required String screenName, Map<String, dynamic> properties, Map<String, dynamic> options})`
Expand All @@ -231,8 +237,8 @@ Segment.screen(
```

### Setting the options globally
You can also set the default options to be used in every method call, if the call omits the options parameter. Just set `SegmentDefaultOptions.instance.options`. For example:

You can also set the default options to be used in every method call, if the call omits the options parameter. Just set `SegmentDefaultOptions.instance.options`. For example:

```dart
SegmentDefaultOptions.instance.options = {
Expand All @@ -245,9 +251,11 @@ SegmentDefaultOptions.instance.options = {
```

## Issues

Please file any issues, bugs, or feature requests in the [GitHub repo](https://github.com/claimsforce-gmbh/flutter-segment/issues/new).

## Contributing

If you wish to contribute a change to this repo, please send a [pull request](https://github.com/claimsforce-gmbh/flutter-segment/pulls).

_<sup>*</sup>This installation method will be removed, please use the [Installation via Dart Code](#via-dart-code) instructions._
_<sup>\*</sup>This installation method will be removed, please use the [Installation via Dart Code](#via-dart-code) instructions._
4 changes: 2 additions & 2 deletions android/build.gradle
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
group 'com.example.flutter_segment'
group 'io.draftea.flutter_segment'
version '3.12.1'

buildscript {
Expand All @@ -24,7 +24,7 @@ apply plugin: 'com.android.library'

android {
if (project.android.hasProperty("namespace")) {
namespace 'com.example.flutterSegment'
namespace 'io.draftea.flutterSegment'
}

compileSdk 33
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.flutter_segment;
package io.draftea.flutter_segment;

import android.os.Bundle;

Expand All @@ -11,13 +11,12 @@ public class FlutterSegmentOptions {
private final Boolean appsflyerIntegrationEnabled;
private final Boolean debug;

public FlutterSegmentOptions(
public FlutterSegmentOptions(
String writeKey,
Boolean trackApplicationLifecycleEvents,
Boolean amplitudeIntegrationEnabled,
Boolean appsflyerIntegrationEnabled,
Boolean debug
) {
Boolean debug) {
this.writeKey = writeKey;
this.trackApplicationLifecycleEvents = trackApplicationLifecycleEvents;
this.amplitudeIntegrationEnabled = amplitudeIntegrationEnabled;
Expand Down Expand Up @@ -47,11 +46,15 @@ public Boolean getDebug() {

static FlutterSegmentOptions create(Bundle bundle) {
String writeKey = bundle.getString("com.claimsforce.segment.WRITE_KEY");
Boolean trackApplicationLifecycleEvents = bundle.getBoolean("com.claimsforce.segment.TRACK_APPLICATION_LIFECYCLE_EVENTS");
Boolean isAmplitudeIntegrationEnabled = bundle.getBoolean("com.claimsforce.segment.ENABLE_AMPLITUDE_INTEGRATION", false);
Boolean isAppsflyerIntegrationEnabled = bundle.getBoolean("com.claimsforce.segment.ENABLE_APPSFLYER_INTEGRATION", false);
Boolean trackApplicationLifecycleEvents = bundle
.getBoolean("com.claimsforce.segment.TRACK_APPLICATION_LIFECYCLE_EVENTS");
Boolean isAmplitudeIntegrationEnabled = bundle
.getBoolean("com.claimsforce.segment.ENABLE_AMPLITUDE_INTEGRATION", false);
Boolean isAppsflyerIntegrationEnabled = bundle
.getBoolean("com.claimsforce.segment.ENABLE_APPSFLYER_INTEGRATION", false);
Boolean debug = bundle.getBoolean("com.claimsforce.segment.DEBUG", false);
return new FlutterSegmentOptions(writeKey, trackApplicationLifecycleEvents, isAmplitudeIntegrationEnabled, isAppsflyerIntegrationEnabled, debug);
return new FlutterSegmentOptions(writeKey, trackApplicationLifecycleEvents, isAmplitudeIntegrationEnabled,
isAppsflyerIntegrationEnabled, debug);
}

static FlutterSegmentOptions create(HashMap<String, Object> options) {
Expand All @@ -60,7 +63,8 @@ static FlutterSegmentOptions create(HashMap<String, Object> options) {
Boolean isAmplitudeIntegrationEnabled = orFalse((Boolean) options.get("amplitudeIntegrationEnabled"));
Boolean isAppsflyerIntegrationEnabled = orFalse((Boolean) options.get("appsflyerIntegrationEnabled"));
Boolean debug = orFalse((Boolean) options.get("debug"));
return new FlutterSegmentOptions(writeKey, trackApplicationLifecycleEvents, isAmplitudeIntegrationEnabled, isAppsflyerIntegrationEnabled, debug);
return new FlutterSegmentOptions(writeKey, trackApplicationLifecycleEvents, isAmplitudeIntegrationEnabled,
isAppsflyerIntegrationEnabled, debug);
}

private static Boolean orFalse(Boolean value) {
Expand Down
Loading