Multi-language Client Implementation

Below are official libraries for common programming languages to connect and call iClick API.

Quick Installation

Node.js, Python, and C# users can directly install via package managers without manually implementing clients:

• Node.js: npm install iclick-auto - 🔗 NPM
• Python: pip install iclick-auto - 🔗 PyPI
• C#: Install-Package iclick-auto - 🔗 NuGet

All these packages implement API calls, event listening, and MetaData binary stream parsing.

Other Languages

The following code examples may not be fully verified and are for reference and learning purposes only. Please ensure thorough testing and validation before using in production environments.

const wserverPort = 23188
const wsevents = {}
let wsclient = null
let reconnectTimer = null

export function reconnect() {
    if( reconnectTimer || wsclient?.readyState === WebSocket.CONNECTING ){
        return
    }
    reconnectTimer = setTimeout(() => {
        console.log('API service reconnecting...')
        connectServer().finally(() => reconnectTimer = null)
    }, 1000 * 3)
}

export function connectServer() {
    return new Promise((_resolve) => {
        
        if( wsclient ){
            return
        }

        wsclient = new WebSocket(`ws://127.0.0.1:${wserverPort}`)
        wsclient.binaryType = 'arraybuffer'

        wsclient.onopen = () => {
            console.log('API service connected successfully')
            _resolve()
        }

        wsclient.onmessage = (_message) => {
     
            let _payload = _message.data,
                _bindata = null

            if( typeof _payload === 'string' ){

                _payload = JSON.parse(_payload)

            }else{

                // Some interfaces return binary data, need to parse [metaDataLength][metaData][binary]
                const _decoder = new TextDecoder('utf-8')   
                const _metaLength = _decoder.decode(_payload.slice(0, 6))
                                    _bindata = _payload.slice(6 + parseInt(_metaLength))
                                    _payload = JSON.parse(_decoder.decode(_payload.slice(6, 6 + parseInt(_metaLength))))
                _payload.data = _bindata
                _bindata = null
            }
            
            const _eventId = _payload.evtid
            const _event = wsevents[ _eventId ]
  
            if( _event ){

                if( _payload.type === 'error' ){
                    _event.reject(new Error(_payload.error))
                }else{
                    _event.resolve( _payload.data )
                }

                delete wsevents[ _eventId ]

            }else if( _payload.event ){

                // You can dispatch events according to different languages
            }
        }
        
        wsclient.onclose = (code) => {

            wsclient = null
            console.log('API service connection closed:', code)
            reconnect()
        }
        
        wsclient.onerror = (err) => {
            console.error('API service connection error:', err)
        }
    })
}


export function apiInvoke(type, _params = {}, _timeout = 18) {

    return new Promise((resolve, reject) => {

        if( !wsclient || wsclient.readyState !== WebSocket.OPEN ){

            reject( new Error('API service connection not ready') )

        }else{

            const _eventId = Math.random().toString(36).substring(2, 12)
            const _payload = {
                ..._params,
                type,
                evtid: _eventId,
                timeout: _timeout
            }

            wsevents[_payload.evtid] = { resolve, reject }

            wsclient.send(JSON.stringify(_payload))

            if( _timeout > 0 ){
                setTimeout(() => {

                    reject(new Error(`API service: ${_payload.evtid} Invoke Timeout !`))

                    delete wsevents[_payload.evtid]

                }, _timeout * 1000)
            }
        }
    })
}

// Usage example
await connectServer()
const result = await apiInvoke('click', { x: 100, y: 200, deviceId: 'XXXXXXXXXX' })

import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import java.net.URI;
import java.nio.ByteBuffer;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicBoolean;
import java.security.SecureRandom;

public class IClient {
    private static final int PORT = 23188;
    private static final SecureRandom RANDOM = new SecureRandom();
    private static final String CHARS = "abcdefghijklmnopqrstuvwxyz0123456789";
    
    private WebSocketClient wsClient;
    private final ConcurrentHashMap<String, CompletableFuture<Object>> events = new ConcurrentHashMap<>();
    private final Gson gson = new Gson();
    private final ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor();
    private final AtomicBoolean isReconnecting = new AtomicBoolean(false);
    
    public synchronized void connect() throws Exception {
        // Close old connection
        if (wsClient != null) {
            wsClient.close();
        }
        
        URI uri = new URI("ws://127.0.0.1:" + PORT);
        wsClient = new WebSocketClient(uri) {
            @Override
            public void onOpen(ServerHandshake handshake) {
                System.out.println("API service connected successfully");
                isReconnecting.set(false);
            }
            
            @Override
            public void onMessage(String message) {
                handleMessage(gson.fromJson(message, JsonObject.class));
            }
            
            @Override
            public void onMessage(ByteBuffer bytes) {
                byte[] data = bytes.array();
                int metaLength = Integer.parseInt(new String(data, 0, 6, StandardCharsets.UTF_8).trim());
                String metaJson = new String(data, 6, metaLength, StandardCharsets.UTF_8);
                handleMessage(gson.fromJson(metaJson, JsonObject.class));
            }
            
            @Override
            public void onClose(int code, String reason, boolean remote) {
                System.out.println("API service connection closed: " + code);
                reconnect();
            }
            
            @Override
            public void onError(Exception ex) {
                System.err.println("API service connection error: " + ex.getMessage());
            }
        };
        
        wsClient.connect();
    }
    
    private void handleMessage(JsonObject payload) {
        if (!payload.has("evtid")) return;
        
        String evtid = payload.get("evtid").getAsString();
        CompletableFuture<Object> future = events.remove(evtid);
        
        if (future != null) {
            if (payload.has("type") && "error".equals(payload.get("type").getAsString())) {
                future.completeExceptionally(new Exception(payload.get("error").getAsString()));
            } else {
                future.complete(payload.get("data"));
            }
        }
    }
    
    private void reconnect() {
        if (!isReconnecting.compareAndSet(false, true)) return;
        
        scheduler.schedule(() -> {
            try {
                System.out.println("API service reconnecting...");
                connect();
            } catch (Exception e) {
                System.err.println("Reconnection failed: " + e.getMessage());
                isReconnecting.set(false);
            }
        }, 3, TimeUnit.SECONDS);
    }
    
    private static String generateEventId() {
        StringBuilder sb = new StringBuilder(10);
        for (int i = 0; i < 10; i++) {
            sb.append(CHARS.charAt(RANDOM.nextInt(CHARS.length())));
        }
        return sb.toString();
    }
    
    public CompletableFuture<Object> invoke(String type, Map<String, Object> params, int timeout) {
        CompletableFuture<Object> future = new CompletableFuture<>();
        
        if (wsClient == null || !wsClient.isOpen()) {
            future.completeExceptionally(new Exception("API service connection not ready"));
            return future;
        }
        
        String evtid = generateEventId();
        Map<String, Object> payload = new HashMap<>(params != null ? params : new HashMap<>());
        payload.put("type", type);
        payload.put("evtid", evtid);
        payload.put("timeout", timeout);
        
        events.put(evtid, future);
        wsClient.send(gson.toJson(payload));
        
        // Set timeout
        scheduler.schedule(() -> {
            CompletableFuture<Object> f = events.remove(evtid);
            if (f != null) {
                f.completeExceptionally(new TimeoutException("API service timeout"));
            }
        }, timeout, TimeUnit.SECONDS);
        
        return future;
    }
    
    public void close() {
        scheduler.shutdown();
        if (wsClient != null) {
            wsClient.close();
        }
    }
    
    // Usage example
    public static void main(String[] args) throws Exception {
        IClient client = new IClient();
        client.connect();
        Thread.sleep(1000);
        
        Map<String, Object> params = new HashMap<>();
        params.put("x", 100);
        params.put("y", 200);
        params.put("deviceId", "XXXXXXXXXX");
        
        client.invoke("click", params, 18)
            .thenAccept(result -> System.out.println("Click result: " + result))
            .exceptionally(ex -> {
                System.err.println("Call failed: " + ex.getMessage());
                return null;
            })
            .thenRun(client::close);
    }
}

package main

import (
    "encoding/json"
    "fmt"
    "math/rand"
    "sync"
    "time"
    
    "github.com/gorilla/websocket"
)

type IClient struct {
    port            int
    conn            *websocket.Conn
    events          map[string]chan Response
    eventsMutex     sync.RWMutex
    reconnectMutex  sync.Mutex
    isReconnecting  bool
}

type Response struct {
    Data  interface{}
    Error error
}

type Payload struct {
    Type    string                 `json:"type,omitempty"`
    EvtID   string                 `json:"evtid,omitempty"`
    Timeout int                    `json:"timeout,omitempty"`
    Event   string                 `json:"event,omitempty"`
    Data    interface{}            `json:"data,omitempty"`
    Error   string                 `json:"error,omitempty"`
}

func NewIClient() *IClient {
    return &IClient{
        port:   23188,
        events: make(map[string]chan Response),
    }
}

func (c *IClient) Connect() error {
    // Close old connection
    if c.conn != nil {
        c.conn.Close()
    }
    
    url := fmt.Sprintf("ws://127.0.0.1:%d", c.port)
    
    conn, _, err := websocket.DefaultDialer.Dial(url, nil)
    if err != nil {
        return fmt.Errorf("connection failed: %w", err)
    }
    
    c.conn = conn
    fmt.Println("API service connected successfully")
    
    go c.messageHandler()
    
    return nil
}

func (c *IClient) messageHandler() {
    defer func() {
        fmt.Println("API service connection closed")
        c.reconnect()
    }()
    
    for {
        messageType, message, err := c.conn.ReadMessage()
        if err != nil {
            return
        }
        
        var payload Payload
        
        switch messageType {
        case websocket.TextMessage:
            if err := json.Unmarshal(message, &payload); err != nil {
                fmt.Printf("JSON parse error: %v\n", err)
                continue
            }
        case websocket.BinaryMessage:
            // Parse binary message
            var metaLength int
            fmt.Sscanf(string(message[:6]), "%d", &metaLength)
            if err := json.Unmarshal(message[6:6+metaLength], &payload); err != nil {
                fmt.Printf("Metadata parse error: %v\n", err)
                continue
            }
            payload.Data = message[6+metaLength:]
        }
        
        c.processPayload(payload)
    }
}

func (c *IClient) processPayload(payload Payload) {
    if payload.EvtID != "" {
        c.eventsMutex.RLock()
        ch, exists := c.events[payload.EvtID]
        c.eventsMutex.RUnlock()
        
        if exists {
            response := Response{Data: payload.Data}
            if payload.Type == "error" {
                response.Error = fmt.Errorf("%s", payload.Error)
            }
            
            ch <- response
            
            c.eventsMutex.Lock()
            delete(c.events, payload.EvtID)
            c.eventsMutex.Unlock()
        }
    }
}

func (c *IClient) reconnect() {
    c.reconnectMutex.Lock()
    if c.isReconnecting {
        c.reconnectMutex.Unlock()
        return
    }
    c.isReconnecting = true
    c.reconnectMutex.Unlock()
    
    time.Sleep(3 * time.Second)
    fmt.Println("API service reconnecting...")
    
    if err := c.Connect(); err != nil {
        fmt.Printf("Reconnection failed: %v\n", err)
    }
    
    c.reconnectMutex.Lock()
    c.isReconnecting = false
    c.reconnectMutex.Unlock()
}

func (c *IClient) generateEventID() string {
    return fmt.Sprintf("%d%03d", time.Now().UnixNano()%1000000000, rand.Intn(1000))
}

func (c *IClient) Invoke(apiType string, params map[string]interface{}, timeout int) (interface{}, error) {
    if c.conn == nil {
        return nil, fmt.Errorf("API service connection not ready")
    }
    
    evtID := c.generateEventID()
    payload := map[string]interface{}{
        "type":    apiType,
        "evtid":   evtID,
        "timeout": timeout,
    }
    for k, v := range params {
        payload[k] = v
    }
    
    ch := make(chan Response, 1)
    c.eventsMutex.Lock()
    c.events[evtID] = ch
    c.eventsMutex.Unlock()
    
    data, _ := json.Marshal(payload)
    if err := c.conn.WriteMessage(websocket.TextMessage, data); err != nil {
        c.eventsMutex.Lock()
        delete(c.events, evtID)
        c.eventsMutex.Unlock()
        return nil, fmt.Errorf("failed to send message: %w", err)
    }
    
    select {
    case response := <-ch:
        return response.Data, response.Error
    case <-time.After(time.Duration(timeout) * time.Second):
        c.eventsMutex.Lock()
        delete(c.events, evtID)
        c.eventsMutex.Unlock()
        return nil, fmt.Errorf("API service timeout")
    }
}

func (c *IClient) Close() error {
    if c.conn != nil {
        return c.conn.Close()
    }
    return nil
}

// Usage example
func main() {
    client := NewIClient()
    if err := client.Connect(); err != nil {
        fmt.Printf("Connection failed: %v\n", err)
        return
    }
    defer client.Close()
    
    time.Sleep(time.Second)
    
    params := map[string]interface{}{
        "x": 100,
        "y": 200,
        "deviceId": "XXXXXXXXXX",
    }
    
    result, err := client.Invoke("click", params, 18)
    if err != nil {
        fmt.Printf("Call failed: %v\n", err)
        return
    }
    
    fmt.Printf("Click result: %v\n", result)
}

Next Steps

• Read more specific API usage examples