Java SDK

Integrate the Java SDK

Add the quickaplus-log-collector-java-sdk-1.0.1-SNAPSHOT.jar JAR file to your project. Contact QT support to obtain the file.

Basic configuration

1. Set the app key

QtSdkConfig.setAppKey("your_app_key"); 

2. Set the data collection endpoint

QtSdkConfig.setQlcEndpoint("your_data_collection_endpoint");

3. Provide authentication credentials

QtSdkConfig.setServiceId("your_ServiceID");
QtSdkConfig.setServiceSecret("your_ServiceSecret");

You can find these credentials in the console under Console > Collection Information > Server-side tracking information.

Set global properties

// Add properties
QtGlobalPropertiesConfig.put("a", "1");
QtGlobalPropertiesConfig.put("b", "2");
// Remove a property
QtGlobalPropertiesConfig.remove("a");
// Get all properties
QtGlobalPropertiesConfig.getAll();
// Clear all properties
QtGlobalPropertiesConfig.clear();

Data reporting

QtLog log = new QtLog.Builder()
        .eventId("order_success")  // Event ID (Required).
        .deviceId("dev-001")		// Device ID. Can be null when reporting user properties ($$_user_profile), but required for all other events.
        .userId("user-001")		// User ID. Required when reporting user properties ($$_user_profile).
        .pageName("pageName")	// Page name (Optional).
        .customProperty(new HashMap<>())		// Custom properties (Optional).
        .systemProperty(new HashMap<>())		// System properties (Optional).
    		.idTracking(new HashMap<>())		// Device identifiers for system properties.
        .debugKey("dk-0001")		// Debug key for tracking validation (Optional). Must be removed before deploying to production.
        .eventTimestamp(System.currentTimeMillis())		// Event timestamp (Required).
        .serverTimestamp(System.currentTimeMillis())  // Server timestamp (Optional).
  			.uuid("xxxx") // Unique identifier for the event log, used to generate the log_id (Supported in v1.0.1 and later).
        .build();		// Build the log object.

Only the system properties listed below are supported. When reporting these properties, the keys must match the table exactly, including case.

Send the log

To send the log, call the following API.

 QtLogSenderHelper.syncSendLog(log);

Demo

package com.alibaba.lingyang.quick.tracking.qlc.java.sdk.model;

import com.alibaba.lingyang.quick.tracking.qlc.java.sdk.config.QtGlobalPropertiesConfig;
import com.alibaba.lingyang.quick.tracking.qlc.java.sdk.config.QtSdkConfig;
import com.alibaba.lingyang.quick.tracking.qlc.java.sdk.sender.QtLogSenderHelper;
import org.junit.Test;

import java.io.UnsupportedEncodingException;
import java.util.HashMap;
import java.util.Map;

/**
 * Test sending a log.
 */
public class TestSendLog {
    @Test
    public void testSend() throws UnsupportedEncodingException {
        // Configuration
        QtSdkConfig.setServiceId("z1212121AOCgtG");
        QtSdkConfig.setServiceSecret("f111111HvkuYu0111111QghlWMpIiU9D");
        QtSdkConfig.setAppKey("123123123");
        QtSdkConfig.setQlcEndpoint("https://log-api.xxxxxxx.com");
        QtSdkConfig.setOpenLog(true);
        QtSdkConfig.setCallback(ctx -> {
            System.out.println(ctx.getResponseCode());
            System.out.println(ctx.getResponseMessage());
            System.out.println(ctx.getSendSuccess());
            System.out.println(ctx.getSendData());
            System.out.println(ctx.getResponseData());
            System.out.println(ctx.getErrors());
        });

        // Add global properties
        QtGlobalPropertiesConfig.put("a", "1");
        QtGlobalPropertiesConfig.put("b", "2");
        // Remove a global property
        QtGlobalPropertiesConfig.remove("a");
        // Get all global properties
        QtGlobalPropertiesConfig.getAll();
        // Clear all global properties
        QtGlobalPropertiesConfig.clear();

        Map<String,String> idTracking = new HashMap();
        idTracking.put("mac","id1");
        idTracking.put("oaid","id2");
        idTracking.put("android_id","id3");

        String a = "Chinese characters";
        String s = new String(a.getBytes("utf8"),"gbk");

        // Custom properties or user properties
        Map<String,Object> customProperty = new HashMap<>();
        customProperty.put("a","1");
        customProperty.put("b",2);

        // System properties
        Map<String,Object> systemProperty = new HashMap<>();
        systemProperty.put("a","1");
        systemProperty.put("b",2);

        // Construct the log object
        QtLog log = new QtLog.Builder()
                .eventId("$$_user_profile") // Event ID (Required). To report user properties, set this to "$$_user_profile".
                .deviceId("dev-001") // Device ID. Can be null when reporting user properties ($$_user_profile), but required for all other events.
                .userId("user-001") // User ID. Required when reporting user properties ($$_user_profile).
                .uuid("xxxx") // Optional.
                .pageName("pageName") // Page name (Optional).
                .idTracking(idTracking) // Device identifiers for system properties (Optional).
                .customProperty(customProperty) // Custom properties or user properties (Optional).
                .systemProperty(systemProperty)// System properties (Optional).
                .serverTimestamp(1111L)
                .debugKey(a)
                .eventTimestamp(System.currentTimeMillis())
                .build();
        // Send the log
        QtLogSenderHelper.syncSendLog(log);
    }

Other configurations

1. Service configuration

   Parameter	Type	Required	Default	Description
   serviceId	String	Yes	-	The service ID for server-side data collection.
   serviceSecret	String	Yes	-	The service secret for server-side data collection.
   qlcEndpoint	String	Yes	-	The data collection endpoint URL.
   appKey	String	Yes	-	Your app key.
   openLog	Boolean	No	false	Specifies whether to enable logging.
   httpConnectTimeoutMillisecond	Integer	No	null	HTTP connection timeout in milliseconds.
   httpWriteTimeoutMillisecond	Integer	No	null	HTTP write timeout in milliseconds.
   httpReadTimeoutMillisecond	Integer	No	null	HTTP read timeout in milliseconds.
   senderType	QtSenderTypeEnum	No	SYNC	Specifies the sending method. Options are synchronous sending or asynchronous sending.
   callback	Consumer<QtSendCallbackContext>	No	null	The callback function.

2. Callback configuration

   Parameter	Type	Description
   sendSuccess	Boolean	Whether the data was sent successfully.
   errors	List<String>	A list of error messages if the sending fails.
   qtLog	QtLog	The QtLog object that was sent.
   responseData	String	The response payload.
   responseCode	String	The response code.
   responseMessage	String	The response message.
   sendData	String	The actual data sent in the HTTP request.

   The following example shows how to register a callback function:

   // Register the callback function
   QtSdkConfig.setCallback(ctx -> {
    System.out.println(ctx.getResponseCode());
    System.out.println(ctx.getResponseMessage());
    System.out.println(ctx.getSendSuccess());
    System.out.println(ctx.getSendData());
    System.out.println(ctx.getResponseData());
    System.out.println(ctx.getErrors());
   });

3. Generate a unique log ID

   The SDK generates a default UUID for each event log to create the log_id. To ensure a unique log_id, you can provide your own UUID:

   QtLog log = new QtLog.Builder()
           .eventId("order_success")  
           .deviceId("dev-001")		
           .userId("user-001")		
           .pageName("pageName")
           .customProperty(new HashMap<>())
           .systemProperty(new HashMap<>())
       		.idTracking(new HashMap<>())
           .debugKey("dk-0001") // Debug key for tracking validation (Optional). Must be removed before deploying to production.
           .eventTimestamp(System.currentTimeMillis())
     			.uuid("xxxx") // Set a unique identifier for the event log to generate the log_id (Supported in v1.0.1 and later).
           .build();