Flutter SDK API Reference

Initializing Hydra SDK for Flutter

Before you can use APIs from the flutter-hydra-lib plugin, ensure the Hydra SDK is initialized successfully.

To initiaize Hydra SDKL for Flutter, follow these steps:

  1. Set up a [HydraNativeEventHandler](https://docs.capillarytech.com/docs/flutter-sdk-api-reference#hydranativeeventhandler-class) and add it using the following code:
    HydraNativeEvents.addEventHandler(handler);
    
  2. Get the SDK initialization result in theonHydraSdkInitializationResult({required bool success, String? error}) callback provided by the handler.
  3. Use the HydraCore class for user management. It includes static functions such as: signUp, signIn, updateUser, signOut, updateGeoConfig, updatePushPreferences, and reportUserEvent.
  4. These functions accept a HydraUserDetails instance, which requires a customerId that must match the configuration on the Capillary CRM dashboard. Use the signUp function to register the user. For subsequent launches, use signIn.
  5. The HydraPushNotification class provides static functions for push notifications: requestPermission and getFCMToken. To receive push notifications, you can ask for permission using requestPermission.
  6. Use getFCMToken to get the FCM token. If you added an event handler in step 1, you also receive the callback in onTokenAvailable.
  7. Use the HydraInbox class to manage them with functions like getInboxMessages, getUnreadInboxMessagesCount, markInboxMessageAsRead, deleteInboxMessage, and deleteAllInboxMessages. The Hydra SDK saves notifications in a database.
  8. Use the HydraInboxUI class functions: showNotificationCenter and hideNotificationCenterIfShowing to use the built-in notification center from the Hydra plugin.
  9. Set the console log level in hydra-config.json. It should be an integer from 0 to 5, where 0 represents off, 1 for error, 2 for warning, 3 for info, 4 for debug, and 5 for verbose. You can also set one of these log levels for remote logging using hydra_remote_log_level in Firebase Remote Configuration.

The [HydraNativeEventHandler](https://docs.capillarytech.com/docs/flutter-sdk-api-reference#hydranativeevent-class-apis) also includes callbacks for onHydraNotificationReceived, onHydraNotificationClicked, onHydraNotificationDismissed, onHydraNotificationShown, and onNotificationCenterDismissed.

HydraCore Class APIs

SignUp

static Future<bool> signUp({
 required HydraUserDetails userDetails,
 Map<String, dynamic>? customData,
});

Parameters

ParameterTypeRequired/OptionalDescription
userDetailsHydraUserDetailsrequiredRead more about this class here
customDataMap<String, dynamic>?optionalCustom attributes for analytics

Returns: Future<bool> indicating if sign up was successfully requested

Usage:

bool signUpResult = await HydraCore.signUp(
 userDetails: userDetails,
);

Sign In

static Future<bool> signIn({
 required HydraUserDetails userDetails,
 Map<String, dynamic>? customData,
});

Parameters

ParameterTypeRequired/OptionalDescription
userDetailsHydraUserDetailsrequiredRead more about this class here
customDataMap<String, dynamic>?optionalCustom attributes for analytics

Returns: Future<bool> indicating if sign in was successfully requested

Usage:

bool signInResult = await HydraCore.signIn(
 userDetails: userDetails,
);

Update User

static Future<bool> updateUser({
 required HydraUserDetails userDetails,
 Map<String, dynamic>? customData,
 List<Map<String, dynamic>>? subscriptions,
});

Parameters

ParameterTypeRequired/OptionalDescription
userDetailsHydraUserDetailsrequiredRead more about this class here
customDataMap<String, dynamic>?optionalCustom attributes for analytics
subscriptionsList<Map<String, dynamic>>?optionalList of Subscriptions with channel, accountId, priority, type and sourcename

Returns: Future<bool> indicating if update was successfully requested

Usage:

bool updateUserResult = await HydraCore.updateUser(
 userDetails: updatedUserDetails,
 customData: {"Key" : "Value"},
 subscriptions: [
   {"channel": "channel1", "type": "topic1", "priority": 1},
 ],
);

Update Geo Config

static Future<bool> updateGeoConfig({
 required HydraGeoConfig config,
});

Parameters

ParameterTypeRequired/OptionalDescription
configHydraGeoConfigrequiredRead more about this class here

Returns: Future<bool> indicating if geo config update was successful

Usage:

bool updateGeoConfigResult = await HydraCore.updateGeoConfig(
    config: config,
);

Sign Out

static Future<bool> signOut({
 required String customerId,
});

Parameters

ParameterTypeRequired/OptionalDescription
customerIdStringrequiredUser's customer ID

Returns: Future<bool> indicating if sign out was successful

Usage:

bool signOutResult = await HydraCore.signOut(
 customerId: "8888888888",
);

Update User Push Preferences

static Future<bool> updatePushPreferences({
 required String customerId,
 required HydraPushPreferences preferences,
});

Parameters

ParameterTypeRequired/OptionalDescription
customerIdStringrequiredUser's customer ID
preferencesHydraPushPreferencesrequiredRead more about this class here

Returns: Future<bool> indicating if preferences update was successful

Usage:

bool result = await HydraCore.updatePushPreferences(
 preferences: pushPreferences,
 customerId: "8888888888",
);

Report custom user events

static Future<bool> reportUserEvent({
 required String eventName,
 Map<String, dynamic>? attributes,
});

Parameters

ParameterTypeRequired/OptionalDescription
eventNameStringrequiredName of the event
attributesMap<String, dynamic>?optionalAdditional event data

Returns: Future<bool> indicating if event reporting was successful

Usage:

bool sendEventResult = await HydraCore.reportUserEvent(
 eventName: "TestEvent",
 attributes:  {"Key" : "Value"},
);

HydraPushNotification class APIs

Get FCM Token

static Future<String> getFCMToken();

Returns: Future<String> containing FCM token (throws error if unavailable)

Usage:

String fcmToken = await HydraPushNotification.getFCMToken();

Request Permission for Push notifications

static Future<bool> requestPermission();

Returns: Future<bool> indicating if permission was granted

Usage:

bool granted = await HydraPushNotification.requestPermission();

HydraInbox class APIs

Get list of Hydra Notifications

static Future<List<HydraNotification>> getInboxMessages();

Returns: Future<List<HydraNotification>>

Usage:

List<HydraNotification> notifications = await HydraInbox.getInboxMessages();

Get Unread Hydra Notifications Count

static Future<int> getUnreadInboxMessagesCount();

Returns: Future<int> with unread count

Usage:

int unreadNotificationCount = await HydraInbox.getUnreadInboxMessagesCount();

Mark a Hydra Notification as read

static Future<bool> markInboxMessageAsRead({
 required HydraNotification notification,
});

Parameters

ParameterTypeRequired/OptionalDescription
notificationHydraNotificationrequiredNotification to mark as read. The list of Hydra Notifications are obtained from here.

Returns: Future<bool> indicating success

Usage:

bool marked = await HydraInbox.markInboxMessageAsRead(notification: notification);

Delete a Hydra Notification

static Future<bool> deleteInboxMessage({
 required HydraNotification notification,
});

Parameters

ParameterTypeRequired/OptionalDescription
notificationHydraNotificationrequiredNotification to delete. The list of Hydra Notifications are obtained from here.

Returns: Future<bool> indicating success

Usage:

bool deleted = await HydraInbox.deleteInboxMessage(notification: notification);

Delete all Hydra Notifications

static Future<bool> deleteAllInboxMessages();

Returns: Future<bool> indicating success

Usage:

bool deleted = await HydraInbox.deleteAllInboxMessages();

HydraInboxUI class APIs

Show In-Built Notification Center

static Future<void> showNotificationCenter();

Usage:

HydraInboxUI.showNotificationCenter();

Hide In-Built Notification Center if Showing

static Future<void> hideNotificationCenterIfShowing();

Usage:

await HydraInboxUI.hideNotificationCenterIfShowing();

HydraNativeEvent class APIs

Add event handler

static void addEventHandler(HydraNativeEventHandler handler);

Parameters

ParameterTypeRequired/OptionalDescription
handlerHydraNativeEventHandlerrequiredHandler instance

Usage:

HydraNativeEvents.addEventHandler(handler);

Remove event handler

static void removeEventHandler(HydraNativeEventHandler handler);

Parameters

ParameterTypeRequired/OptionalDescription
handlerHydraNativeEventHandlerrequiredHandler instance

Usage:

HydraNativeEvents.removeEventHandler(handler);

Remove all event handlers

static void removeAllEventHandlers();

Usage:

HydraNativeEvents.removeAllEventHandlers();

HydraNativeEventHandler class

class HydraNativeEventHandler {
 void onTokenAvailable({required String token}) {}
 void onHydraNotificationReceived({required HydraNotification notification}) {}
 void onHydraNotificationClicked({HydraNotificationCTA? cta, HydraNotification? notification}) {}
 void onHydraNotificationDismissed({required HydraNotification notification}) {}
 void onHydraNotificationShown({required HydraNotification notification}) {}
 void onNotificationCenterDismissed() {}
 void onHydraSdkInitializationResult({required bool success, String? error}) {}
}

Callback Descriptions

  • onTokenAvailable: New FCM token available
  • onHydraNotificationReceived: Notification received
  • onHydraNotificationClicked: Notification/CTA clicked
  • onHydraNotificationDismissed: Notification dismissed
  • onHydraNotificationShown: Notification shown
  • onNotificationCenterDismissed: Notification center closed
  • onHydraSDKInitializationResult: SDK initialization result

HydraCore Model Classes and Enumerations

HydraUserDetails

HydraUserDetails({
 required this.customerId,
 this.email,
 this.phoneNumber,
 this.firstName,
 this.lastName,
});

Parameters

ParameterTypeRequired/OptionalDescription
customerIdStringrequiredUser identifier
firstNameString?optionalUser's first name
lastNameString?optionalUser's last name
emailString?optionalUser's email
phoneNumberString?optionalUser's phone number

Usage:

HydraUserDetails userDetails = HydraUserDetails(
 customerId: '8888888888',
 firstName: 'FirstName',
 lastName: 'LastName',
 email: '[email protected]',
 phoneNumber: '918888888888',
);

HydraGeoConfig

HydraGeoConfig({
 required this.city,
 required this.country,
 required this.countryCode,
 this.timezone,
});

Parameters

ParameterTypeRequired/OptionalDescription
cityStringrequiredUser's city
countryStringrequiredUser's country
countryCodeStringrequiredCountry code
timezoneString?optionalTimezone

Usage:

HydraGeoConfig geoConfig = HydraGeoConfig(
 city: "Bangalore",
 country: "India",
 countryCode: "IN",
 timezone: "Asia/Kolkata",
);

HydraPushPreferences

HydraPushPreferences({
 required this.promPushEnabled,
 required this.transPushEnabled,
});

Parameters

ParameterTypeRequired/OptionalDescription
promPushEnabledboolrequiredPromotional pushes
transPushEnabledboolrequiredTransactional pushes

Usage:

HydraPushPreferences pushPreferences = HydraPushPreferences(
     promPushEnabled: false,
     transPushEnabled: true,
);

HydraNotification Model Classes

HydraNotification Structure

class HydraNotification {
 final String? cuid;
 final String? scope;
 final String? campaignId;
 final String? variationId;
 // ... (other properties)
 final HydraNotificationGateway? gateway;
 final HydraNotificationBody? body;
 final HydraNotificationExpandedDetails? expandableDetails;
 // ... (other properties)
}

HydraNotificationBody

class HydraNotificationBody {
 final String? title;
 final String? message;
 final String? image;
 final HydraNotificationCTA? cta;
}

HydraNotificationCTA

class HydraNotificationCTA {
 final HydraNotificationCTAType? type;
 final String? action;
 final String? actionText;
}

HydraNotificationCTAType Enum

enum HydraNotificationCTAType {
 external,
 deepLink,
 rating,
 feedback,
 appRating,
 unknown,
}

HydraNotificationExpandedDetails

class HydraNotificationExpandedDetails {
 final List<HydraNotificationCTA>? ctas;
 final String? message;
 final String? image;
 final String? style;
}

HydraNotificationGateway Enum

enum HydraNotificationGateway {
 fcm,
 xiaomi,
 unknown,
}