Installation

Follow the steps to set up and start using the Flutter ADK in your project.

1. Install the ADK Package

Add the ADK to your Flutter project's pubspec.yaml:

dependencies:
  art_adk: ^0.0.1

Then run:

flutter pub get

2. Import the ADK into your project

Import the ADK in your Dart files to use the features provided by ART:

import 'package:art_adk/art_adk.dart';

Everything is asynchronous by default — Flutter uses Future/async/await, so there is no separate sync/async variant.

3. Generate Client Secret

Once you have access to the ART Live Dashboard, generate the Client Secret and place the credential file at assets/adk-services.json in your project. The JSON looks like:

{
    "Client-ID": "xxxxxxxxxx",
    "Client-Secret": "xxxxxxxxxxx",
    "Org-Title": "YOUR_ORG",
    "ProjectKey": "YOUR_PROJECT_KEY",
    "Environment": "YOUR_ENV_NAME"
}

Register the asset in your pubspec.yaml:

flutter:
  assets:
    - assets/adk-services.json

important

The adk-services.json needs to be updated with ProjectKey and Environment, manually. To learn how to obtain the values, click here

4. Get Passcode

Before authenticating, obtain a passcode for the user. Pass the credentials loaded in step 3:

final credentials = await AppConfigLoader.loadCredentials();

  final passcode = await AuthService.connectWithPasscode(
    username: 'your_username',   // Replace with your username
    firstName: 'first_name',     // Replace with your first name
    lastName: 'last_name',       // Replace with your last name
    credentials: credentials,
  );
  var updatedCreds = credentials.copyWith(accessToken: passcode);

5. Authenticate

Once the client credentials are loaded and you have a passcode, initialize the ADK and connect. For short-lived workflows, wrap connect / disconnect in a try / finally:

final config = AdkConfig(
  uri: 'YOUR_WEBSOCKET_URI',      // Replace with ART server WebSocket URI
  authToken: "YOUR_PASS_CODE",      // Use the passcode from step 4
  getCredentials: () => updatedCreds,
);

final adk = Adk(adkConfig: config);

try {
  // Initiate the connection to the ART server
  await adk.connect();
  // Your logic here
} finally {
  await adk.disconnect();
}

6. Subscribe to Channel

A Channel is a communication pathway that provides passage for data transfer. Subscribing to a channel lets you use real-time messaging in your application:

// Subscribe to your regular channel
final subscription = await adk.subscribe(channel: 'your-channel-name');

  // For subscribing secure channel need this extra steps to Generate a new key pair and register the public key with the ART server
final keyPair = await adk.generateKeyPair();
// Set the key pair for encryption/decryption
await adk.setKeyPair(keyPair);
final subscription = await adk.subscribe(channel: 'your-secure-channel-name');

You can learn more about Channel Configuration from here

7. Push Messages

Messages are pushed to a channel using the push() method. This method allows you to send various event types with associated data, and optionally target specific users within the channel for granular delivery.

// Define the message payload
final payload = <String, dynamic>{'content': 'Hello from ART ADK!'};

// Optionally define specific target users within the channel
final targetUsers = <String>['username1', 'username2'];

try {
  await subscription.push(
    event: 'message',
    data: payload,
    options: PushConfig(to: targetUsers), // Target specific recipients
  );
  log('Message pushed successfully');
} catch (error) {
  log('Failed to push message: $error');
}

🔒 Secure / targeted channels require exactly one recipient in PushConfig(to: [...]).

8. Listen to All Events and Messages

Bind handlers to events on the subscription's emitter. This delivers every incoming payload for the bound event type:

subscription.emitter.on('message', (dynamic data) {
  log('Received: $data');
});

To listen to every event on a default (non-CRDT) channel, cast and use listen():

  subscription.listen((Map<String, dynamic> data) {
    log("Event '${data['event']}' → ${data['content']}");
  });