Installation

Follow the steps to set up and start using the Objective-C ADK in your project.

1. Add via Swift Package Manager (Xcode)

• Open your project in Xcode
• Go to File → Add Packages
• Enter the repository URL: https://github.com/aiotrixdev/art-objectivec-adk.git

Or using CocoaPods

Add this to your Podfile:

pod 'ArtAdk', '~> 1.0.0'

Then run pod install in your terminal.

pod install

2. Import the ADK into your project

Import the ADK in your Objective-C files to use the features provided by ART:

@import ArtAdk

3. Configure Client Credentials

Once you have access to the ART Live Dashboard, generate the Client Secret and Create a credential object:

CredentialStore *creds = [[CredentialStore alloc]
    initWithEnvironment:@"YOUR_ENV"
             projectKey:@"YOUR_PROJECT_KEY"
               orgTitle:@"YOUR_ORG"
               clientID:@"xxxxxxxxxx"
           clientSecret:@"xxxxxxxxxxx"];

• Drag adk-services.json into Xcode
• Ensure:
  • "Add to target" is checked

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:

- (void)fetchPasscodeWithCredentials:(CredentialStore *)creds
                          completion:(void (^)(NSString *passcode, NSError *error))completion {
    NSURL *url = [NSURL URLWithString:@"https://dev.arealtimetech.com/ws/v1/connect/passcode"];
    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
    request.HTTPMethod = @"POST";

    [request setValue:creds.clientID forHTTPHeaderField:@"Client-Id"];
    [request setValue:creds.clientSecret forHTTPHeaderField:@"Client-Secret"];
    [request setValue:creds.orgTitle forHTTPHeaderField:@"X-Org"];
    [request setValue:creds.environment forHTTPHeaderField:@"Environment"];
    [request setValue:creds.projectKey forHTTPHeaderField:@"ProjectKey"];
    [request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

    NSDictionary *body = @{
        @"username": @"your_username",
        @"first_name": @"first_name",
        @"last_name": @"last_name"
    };

    NSError *jsonError = nil;
    request.HTTPBody = [NSJSONSerialization dataWithJSONObject:body
                                                       options:0
                                                         error:&jsonError];
    if (jsonError) {
        completion(nil, jsonError);
        return;
    }

    [[[NSURLSession sharedSession] dataTaskWithRequest:request
                                     completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
        if (error) {
            completion(nil, error);
            return;
        }

        NSDictionary *json = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
        NSDictionary *dataObj = [json isKindOfClass:[NSDictionary class]] ? json[@"data"] : nil;
        NSString *passcode = [dataObj isKindOfClass:[NSDictionary class]] ? dataObj[@"passcode"] : nil;

        completion(passcode ?: @"", nil);
    }] resume];
}

5. Authenticate

Once the client credentials are loaded and you have a passcode, initialize the ADK and connect:

// Assume passcode is already fetched
NSString *passcode = self.passcode;

// Create configuration
AdkConfig *config = [[AdkConfig alloc]
    initWithUri:@"YOUR_WEBSOCKET_URI"
      authToken:passcode
 getCredentials:^CredentialStore *{
    return creds; // previously created CredentialStore
}];

// Initialize ADK
Adk *adk = [[Adk alloc] initWithConfig:config];

// Connect
[adk connect:nil completion:^{
    NSLog(@"Connected successfully");

    // Your logic here

    // Disconnect when done
    [adk disconnect:^{
        NSLog(@"Disconnected successfully");
    }];
}];

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
[adk subscribe:@"your-channel-name"
    completion:^(BaseSubscription *subscription, NSError *error) {
        // Subscription ready
    }];

// For subscribing secure channel need this extra steps to Generate a new key pair and register the public key with the ART server
[adk generateKeyPair:^(KeyPairType *keyPair, NSError *error) {
    [adk subscribe:@"your-secure-channel-name"
        completion:^(BaseSubscription *secureSubscription, NSError *subError) {
            // Secure subscription ready
        }];
}];

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
NSDictionary *payload = @{
    @"content": @"Hello from ART ADK!"
};

PushConfig *targetUsers = [[PushConfig alloc] initWithTo:@[@"username1", @"username2"]];

[subscription push:@"message"
              data:payload
           options:targetUsers
        completion:^(NSError *error) {
            if (error) {
                NSLog(@"Failed to push message: %@", error);
            } else {
                NSLog(@"Message pushed successfully");
            }
        }];

🔒 Secure / targeted channels require exactly one recipient.

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" handler:^(id data) {
    NSLog(@"Received: %@", data);
}];

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

if ([subscription isKindOfClass:[Subscription class]]) {
    Subscription *typedSub = (Subscription *)subscription;
    [typedSub listen:^(NSDictionary<NSString *, id> *message) {
        NSLog(@"Event %@ → %@", message[@"event"], message[@"content"]);
    }];
}