How to implement server-side tracking with the Java SDK - Quick Tracking

Integrate the Quick Tracking Java SDK into your server-side application to collect and report tracking data.

Integrate the Java SDK

Manually import the `quickaplus-log-collector-java-sdk-1.0.1-SNAPSHOT.jar` package. To obtain the package, contact QT support.

Basic configuration (Required)

Important

You must set the appkey, data collection domain name, and authentication information.

1. Set the appkey

QtSdkConfig.setAppKey("Your appkey");

2. Set the data collection domain name

QtSdkConfig.setQlcEndpoint("Your data collection domain name");

Note

The SDK automatically appends `/server` to the data collection endpoint when reporting data. Do not add this path in your code.

3. Enter authentication information

QtSdkConfig.setServiceId("Your ServiceID");
QtSdkConfig.setServiceSecret("Your ServiceSecret");

This information is available in the Server Tracking Information section under Management Console > Collect Information.

Global property settings

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

Report tracking data

QtLog log = new QtLog.Builder()
        .eventId("order_success")  // Event code (required)
        .deviceId("dev-001")		// Set the device ID. You must set either the device ID or the user ID.
        .userId("user-001")		// Set the user ID. You must set either the device ID or the user ID.
        .pageName("pageName")	// Set the page code (optional)
        .customProperty(new HashMap<>())		// Set event properties (optional)
        .systemProperty(new HashMap<>())		// Set system properties (optional)
    		.idTracking(new HashMap<>())		// Set the device identifier for system properties
        .debugKey("dk-0001")		// Set the flag for tracking validation (optional). Delete this before publishing.
        .eventTimestamp(System.currentTimeMillis())		// Set the client timestamp (required)
        .serverTimestamp(System.currentTimeMillis())  // Set the server timestamp (optional)
  			.uuid("xxxx") // Set the unique identifier for the event log to generate a log_id (supported in version 1.0.1)
        .build();		// Log construction is complete

Only the following system properties are supported. Keys are case-sensitive and must match exactly.

Category	Developer-reported field & QT system property field	Type	Description
Application info	channel	String	Application channel
Application info	app_version	String	Application version
SDK info	sdk_version	String	SDK version
SDK info	sdk_type	String	SDK type
System info	os	String	Operating system
System info	os_version	String	Operating system version
Device info	resolution	String	Screen resolution
	mac, oaid, openid, unionid, android_id, idfa, serial, imei, idfv	String	Device identifier. Report this using `idTracking(new HashMap<>())`. For more information, see the demo above.
	device_brand	String	Device brand
	device_model	String	Device model
Network and carrier	access	String	Network type
	access_subtype	String
	carrier	String	Carrier
Platform and scenario info	scene	String	Scenario value (Mini Program)
Platform and scenario info	device_type	String
Extracted from http_header and user agent	browser	String	Browser
Extracted from http_header and user agent	ip	String	IP address

Send logs

Call the following method to send a log.

 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 logs
 */
public class TestSendLog {
    /**
     * Test
     */
    @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");
        // Delete 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";
        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("$$_uer_profile") // Event code (required). If you are reporting a user property event, set the code to $$_user_profile.
                .deviceId("dev-001") // Set the device ID. You must set either the device ID or the user ID.
                .userId("user-001") // Set the user ID. You must set either the device ID or the user ID. This is required for $$_user_profile events.
                .uuid("xxxx") // (Optional)
                .pageName("pageName") // Set the page code (optional)
                .idTracking(idTracking) // Set the device identifier for system properties (optional)
                .customProperty(customProperty) // Set event properties or user properties (optional)
                .systemProperty(systemProperty)// Set system properties (optional)
                .serverTimestamp(1111L)
                .debugKey(a)
                .eventTimestamp(System.currentTimeMillis())
                .build();
        // Send the log
        QtLogSenderHelper.syncSendLog(log);
    }

Other configurations

Service configuration

Configuration	Type	Required	Default	Description
serviceId	String	Yes	-	The AccessKey ID for server-side collection.
serviceSecret	String	Yes	-	The AccessKey secret for server-side collection.
qlcEndpoint	String	Yes	-	Data collection service endpoint.
appKey	String	Yes	-	appkey
openLog	Boolean	No	false	Enables SDK 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	Sending mode: synchronous or asynchronous.
callback	Consumer<QtSendCallbackContext>	No	null	Callback function.

Callback configuration

Property	Type	Description
sendSuccess	Boolean	Whether the log was sent successfully.
errors	List<String>	A list of error messages for failed sending attempts.
qtLog	QtLog	The QtLog object that was sent.
responseData	String	Response body.
responseCode	String	Response status code.
responseMessage	String	Response message.
sendData	String	The HTTP request payload.

Callback function registration example

// 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());
});

Generate a unique log ID (log_id)

By default, the SDK generates a UUID for each event log as the `log_id`. You can also set the UUID manually for greater control:

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")// Set the flag for tracking validation (optional). Delete this before publishing.
        .eventTimestamp(System.currentTimeMillis())
  			.uuid("xxxx") // Set the unique identifier for the event log to generate a log_id (supported in version 1.0.1)
        .build();