Zeta Flutter Mobile SDK 0.1.0

The Zeta Flutter Mobile SDK 0.1.0 allows Flutter apps to integrate with Zeta’s native SDKs (iOS and Android). The SDK supports features including:

• User identity and profile management

• Event tracking (auto-events, custom events, screen views)

• In-app messaging

• Push notifications (token updates, click tracking, rich notifications)

• Location tracking

• Deep linking / intent handling

Compatibility

The native SDKs are:

• zeta-ios-sdk v0.1.7

• zeta-android-sdk v0.1.7

Installation

1. Add the plugin to your Flutter project’s pubspec.yaml:

dependencies:
  zetakit_flutter:
    git:
      url: https://gitlab.com/zeta-crm/zetakit-flutter.git
      ref: 0.1.0

2. Run:

flutter pub get

3. Import into your Dart code:

import 'package:zetakit_flutter/zetakit_flutter.dart';

Initializing the SDK

Call initialization early, e.g. inside main() before runApp():

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  bool success = await ZetaCore().initialize(
    ZetaInitConfig(
      clientSiteId: "YOUR_SITE_ID",
      clientSecret: "YOUR_CLIENT_SECRET",
      optIn: true,
      region: ZetaRegion.us,             // adjust to your account region
      isLoggingEnabled: true,
      appGroupId: 'group.com.zetaglobal.Zeta-Sample-App',  // optional
      appEnvironment: ZTAppEnvironment.PRODUCTION
    )
  );
  if (success) {
    print("✅ Zeta SDK initialized successfully");
  } else {
    print("❌ Zeta SDK initialization failed");
  }
  runApp(MyApp());
}

Important config fields:

• clientSiteId & clientSecret: Credentials from Zeta Marketing Platform (ZMP) console.

• optIn: Boolean. If false, SDK will start in the opted-out state. No event tracking until opt-in.

• region: Zeta account region.

• isLoggingEnabled: Enables verbose logs for debugging. Default is off.

• appGroupId: (iOS only) For Notification Service Extension and tracking notification delivery.

• appEnvironment: “Production” by default; helps select proper environment (APNS, etc.)

There is also support for native initialization on iOS and Android (within AppDelegate or Application classes), using equivalent config objects.

Session & Identity Management

• BSIN (Browser/Session Identification Number):

  • Listen for BSIN change: ZetaCore.onBsinChanged.listen(...)

  • Get current (cached) BSIN: await ZetaCore().getCachedBsin()

• Opt-in / Opt-out tracking:

  • Opt-out: setting optIn: false during initialization or via method await ZetaCore().optOutFromTracking()

  • Opt-in: set optIn: true in initialization or via method await ZetaCore().optInForTracking(uid)

  • Note: If you rely on a mutable opt-in/out state, you must ensure it's preserved across app restarts; re-initialization might override previous status.

• User details/properties:
  Use ZetaCore().setUserDetails(...). You can set:

  • name, firstName, lastName

  • email & phone, each with optional additional info (e.g. subscriptionStatus, contactProperties)

  • source, uid, signedUpAt, and any custom or additional properties.

• Clearing user identity:
  await ZetaCore().clear() removes the stored user session. Recommended when the user logs out or the profile changes significantly.

• Advertising IDs / App Set IDs:

  • setAppSetId(...)

  • setAdvertisementId(...) (e.g., GAID, IDFA)

Event Tracking

• Automatic events (handled by SDK):

• Screen tracking:
  Track navigation/screen names:

  DART

  await ZetaCore().trackScreenName(
    screenName: String,
    deeplink: String?,
    properties: Map<String, dynamic>?
  );

• Custom events:
  Send events with name + JSON-serializable properties:

  DART

  await ZetaCore().sendCustomEvent(
    eventName: "some_event_name",
    properties: { "key1": value1, "key2": value2 }
  );

If any property value is not JSON-serializable, the whole event will be silently discarded.

Location Tracking

You can track user location by calling:

await ZetaCore().trackLocation(
  latitude,
  longitude,
  isForeground: isForegroundBoolean
);

• isForeground: indicates whether the location is collected in the foreground or background.

• The location is cached in memory; subsequent events will include the location property if available.

Push Notifications

1. Update device token

   DART

   await ZetaCore().updatePushToken("DEVICE_TOKEN");

2. iOS Setup

   • Add pods in Podfile: ZetaCore and ZetaNotificationService. For rich notifications, include a notification service extension.

   • Handle user notification center delegate to track notification clicked: use userNotificationCenter(_:didReceive:withCompletionHandler:) and call ZetaClient.shared.push?.userNotificationCenter(...) or trackNotificationClicked(...).

3. Android Setup

   • Ensure google-services.json is properly placed.

   • Add Firebase Messaging dependency, ensure Google Play Services are available.

   • For Android 13+, request notification permission.

4. Notification click & deep links

   • Listen for push notification click events using ZetaCore.onZetaNotificationClick.listen(...) in Dart. Extract data like deeplink, extra payload.

   • Native handling is also possible: Android intents and iOS delegate callbacks.

5. Rich Notifications (iOS)

   • Supports images (JPG, PNG, GIF) and video (MP4) content in push notifications.

   • Use ZetaNotificationService to track delivery and manage rich content.

6. Push notification channel & display options (Android)

   • Configure through ZTNotificationConfig and ZTNotificationChannel (icon, color, sound, channel settings, etc.)

In-App Messaging

• In-app messages are toaster/pop-up style messages shown inside the app. These do not require additional permissions.

• By default, in-app messaging is enabled after initialization. SDK polls the server for messages and will show them when appropriate.

• You can register to listen to lifecycle events:

  CODE

  ZetaCore.onInAppWillAppear.listen(...)  
  ZetaCore.onInAppDidAppear.listen(...)  
  ZetaCore.onInAppClicked.listen(...)  
  ZetaCore.onInAppDismissed.listen(...)  

• Check if in-app messaging is active:

  CODE

  bool isActive = await ZetaCore().getInAppStatus();

• Stop/start in-app messages:

  CODE

  await ZetaCore().stopInApp();
  await ZetaCore().startInApp();

  Note: the stop state is not persisted automatically. If the app restarts, in-app messaging will be active unless you manually manage that state.

Deep Linking & Intent Handling

• Flutter side: listen for ZetaCore.onDeeplinkReceived.listen(...) to be notified of deeplink + extra info payloads.

• Android side: configure intent filters in AndroidManifest.xml to support deep link URIs.

• For push notifications, deeplink data in payloads can be used to navigate within the app.

Notes & Best Practices

• All datetime properties (e.g., signedUpAt, lastSent, etc.) should be in ISO 8601 format and in UTC.

• When setting user contact preferences or subscription statuses, only valid/predefined values in ZMP are allowed. Custom keys via additionalProperties are supported.

• Make sure your app handles both foreground and background states correctly, for example, with permission requests (on Android for notifications) and for location tracking.

• Always replace placeholder values (YOUR_SITE_ID, YOUR_CLIENT_SECRET, etc.) with actual values from your ZMP account.

• Handle failures gracefully: initialization might fail, device token updates might fail, permission requests might be denied, etc.