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:
- 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);
- Get the SDK initialization result in the
onHydraSdkInitializationResult({required bool success, String? error})
callback provided by the handler. - Use the HydraCore class for user management. It includes static functions such as: signUp, signIn, updateUser, signOut, updateGeoConfig, updatePushPreferences, and reportUserEvent.
- 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.
- The HydraPushNotification class provides static functions for push notifications: requestPermission and getFCMToken. To receive push notifications, you can ask for permission using requestPermission.
- Use getFCMToken to get the FCM token. If you added an event handler in step 1, you also receive the callback in onTokenAvailable.
- Use the HydraInbox class to manage them with functions like getInboxMessages, getUnreadInboxMessagesCount, markInboxMessageAsRead, deleteInboxMessage, and deleteAllInboxMessages. The Hydra SDK saves notifications in a database.
- Use the HydraInboxUI class functions: showNotificationCenter and hideNotificationCenterIfShowing to use the built-in notification center from the Hydra plugin.
- 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
Parameter | Type | Required/Optional | Description |
---|---|---|---|
userDetails | HydraUserDetails | required | Read more about this class here |
customData | Map<String, dynamic>? | optional | Custom 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
Parameter | Type | Required/Optional | Description |
---|---|---|---|
userDetails | HydraUserDetails | required | Read more about this class here |
customData | Map<String, dynamic>? | optional | Custom 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
Parameter | Type | Required/Optional | Description |
---|---|---|---|
userDetails | HydraUserDetails | required | Read more about this class here |
customData | Map<String, dynamic>? | optional | Custom attributes for analytics |
subscriptions | List<Map<String, dynamic>>? | optional | List 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
Parameter | Type | Required/Optional | Description |
---|---|---|---|
config | HydraGeoConfig | required | Read 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
Parameter | Type | Required/Optional | Description |
---|---|---|---|
customerId | String | required | User'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
Parameter | Type | Required/Optional | Description |
---|---|---|---|
customerId | String | required | User's customer ID |
preferences | HydraPushPreferences | required | Read 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
Parameter | Type | Required/Optional | Description |
---|---|---|---|
eventName | String | required | Name of the event |
attributes | Map<String, dynamic>? | optional | Additional 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
Parameter | Type | Required/Optional | Description |
---|---|---|---|
notification | HydraNotification | required | Notification 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
Parameter | Type | Required/Optional | Description |
---|---|---|---|
notification | HydraNotification | required | Notification 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
Parameter | Type | Required/Optional | Description |
---|---|---|---|
handler | HydraNativeEventHandler | required | Handler instance |
Usage:
HydraNativeEvents.addEventHandler(handler);
Remove event handler
static void removeEventHandler(HydraNativeEventHandler handler);
Parameters
Parameter | Type | Required/Optional | Description |
---|---|---|---|
handler | HydraNativeEventHandler | required | Handler 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
Parameter | Type | Required/Optional | Description |
---|---|---|---|
customerId | String | required | User identifier |
firstName | String? | optional | User's first name |
lastName | String? | optional | User's last name |
String? | optional | User's email | |
phoneNumber | String? | optional | User'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
Parameter | Type | Required/Optional | Description |
---|---|---|---|
city | String | required | User's city |
country | String | required | User's country |
countryCode | String | required | Country code |
timezone | String? | optional | Timezone |
Usage:
HydraGeoConfig geoConfig = HydraGeoConfig(
city: "Bangalore",
country: "India",
countryCode: "IN",
timezone: "Asia/Kolkata",
);
HydraPushPreferences
HydraPushPreferences({
required this.promPushEnabled,
required this.transPushEnabled,
});
Parameters
Parameter | Type | Required/Optional | Description |
---|---|---|---|
promPushEnabled | bool | required | Promotional pushes |
transPushEnabled | bool | required | Transactional 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,
}
Updated 1 day ago