Quick Tracking:Android Visualization Tracking Integration Documentation

Version support

Visualization tracking SDK only supports Android 4.0 or higher (api level >= 14). On devices below the Android 4.0, the visualization tracking feature does not work.

SDK dependencies

The visualization tracking SDK must be used together with the Privatized Statistics SDK and Privatized SPM plug-in SDK.

Please refer to Privatization Statistics SDK and Privatization SPM plug-in to integrate the corresponding SDK into your application first.

Control support list

The current version of the visualization tracking SDK supports only the controls listed in the following table. Controls that are not listed in the list have not yet been tested for compatibility, and their validity and accuracy cannot be guaranteed at this time. Tracking control types outside the list does not guarantee successful reporting of related data.

Integrate the SDK

SDK download

SDK download URL: Android SDK

SDK integration

Decompress the downloaded release.zip package and copy the two AAR packages to the libs directory in the directory of the host app. If your project does not have this directory, you must create one.

Android Studio project configuration

In the android configuration section of the module compilation script build.gradle corresponding to the host application, you need to add the following configuration:

repositories {
        flatDir {
            dirs 'libs'
        }
    }

In the dependencies configuration section of the module compilation script build.gradle for the host application, add the following dependencies:

Visualization SDKs must be used together with the Privatized Statistics SDK and the SPM plug-in. If you do not find the Statistics SDK and SPM plug-in in the visualization SDK package, see Import and Configure SDK for the Android SDK.

// Import the Privatization Statistics SDK and the SPM plug-in.
    implementation files('libs/umeng-common-1.2.0.P.jar')
    implementation files('libs/umeng-spm-1.2.0.jar')

    // Import the visualization tracking SDK.
    // The tracker-config package is imported only in the tracking mode. Do not import the package in the online mode. 
    implementation files('libs/tracker-config-1.1.2.P.aar')
    implementation files('libs/tracker-release-1.1.2.P.aar')

• The tracker-release is a package that must be imported to use the visualization tracking function and must be introduced.

• The tracker-config package is only dependent on the tracking configuration mode. Please do not import this package for the online version of App.

Permission configuration

The following permission declaration needs to be added to the hosting app manifest file, AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

Obfuscation configuration

If your application uses code obfuscation, add the following configuration to prevent the visualization tracking SDK from being unavailable due to secondary obfuscation.

# SDK obfuscation configuration (important: must be set to enable code obfuscation)

-keep class com.umeng.** {*;}

-keepclassmembers class * {
   public <init> (org.json.JSONObject);
}
-keepclassmembers enum * {
    public static **[] values();
    public static ** valueOf(java.lang.String);
}

SDK initialization

The visualization tracking SDK does not need to be initialized. The initialization function UMConfigure.init checks whether the host app has imported the visualization tracking SDK. If the host app has been integrated, it automatically calls the visualization tracking SDK initialization function by reflection. You can initialize the visualization tracking SDK based on the initialization requirements of the privatization statistics SDK.

The statistics SDK pre-initialization function must be executed in the main thread of the Application.onCreate function of the hosting app:

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

                // Set the data collection endpoint. Note: You need to set your own data collection endpoint.
                UMConfigure.setCustomDomain("https://log-api.aplus.emas-poc.com", null);
        
        UMConfigure.setLogEnabled(true);
        // Pre-initialization. Please change the appkey and channel parameters to the corresponding values of your app.
        final String useAppkey = "91547686";
        final String useChannel = "test_channel";

        // preInit The preinitialization function must be executed in the Application.onCreate function thread. 
        UMConfigure.preInit(this, useAppkey, useChannel);
        
        /**
         * Initialize the statistics SDK. Note: The init initialization function needs to be called after the customer agrees to the privacy authorization agreement.
         */
        final Context appContext = this.getApplicationContext();
        final ScheduledThreadPoolExecutor executor = new ScheduledThreadPoolExecutor(1);
        executor.schedule(new Runnable() {
            @Override
            public void run() {
                Log.i(TAG, "--->>> Delay 5 seconds to call the initialization API: UMConfigure.init() ");
                UMConfigure.init(appContext, useAppkey, useChannel, UMConfigure.DEVICE_TYPE_PHONE, null);
            }
        }, 5, TimeUnit.SECONDS);
    }
}

Control unique ID settings

For each control that needs to report logs in APP, an ID that can uniquely identify the control is required, so that the control can be accurately located when traversing the component tree. Set control uniqueness ID Set method call:

ViewTools.setViewId(View view, String id)

• [Important] For controls with "waterfall flow" characteristics such as ListView and RecycleView, in order to reduce the tracking configuration of business parties on the visual interface, a unified ID is set for each component in the control, and the following APIs are strongly recommend to be called by distinguishing it through its location information or sub-control name:

The SDK provides the following two APIs for sub-ID setting

A. Distinguishing controls by position

ViewTools.setViewId(View view, String id, int position)

For example, you can set a unique ID for each item in RecycleView.

B. Distinguishing controls by custom child control names

ViewTools.setViewId(View view, String id, String subViewId)

Debug logs

After the visualization tracking SDK module is initialized, relevant logs are printed with the log tag "VTTracker". The log content contains the current SDK working mode.

• Config Mode indicates that the current SDK works in visualization tracking configuration mode. This mode can be used with front-end page tracking.

com.umeng.abtest I/VTTracker: Config Mode: SDK Init complete.

• Release Mode indicates that the current SDK works in visualization tracking mode. In this mode, the SDK pulls visualization tracking configurations and sends statistical logs when the corresponding event is triggered.

com.umeng.abtest I/VTTracker: Release Mode: SDK Init complete.

SDK integration Demo

Source code of the Demo project: Android visual tracking demo

FAQ

1. How do I track on an activity or fragment page to enable the visualization tracking feature on the current page?

The visualization tracking function on this page can be supported only on the Activity or Fragment page for which manual PV tracking and SPM coding are completed in advance.

Sample code for manual PV tracking and SPM-coded tracking:

@Override
    protected void onResume() {

        super.onResume();
        MobclickAgent.onPageStart("MainPage"); // Manual PV tracking on the page
        SpmAgent.updateCurSpm(this, "MainPage"); // Set the SPM encoding.

    }

@Override
    protected void onPause() {
    
        super.onPause();
        MobclickAgent.onPageEnd("MainPage"); // Manual PV tracking for the page
        
    }

For a page that has not completed manual PV tracking (call MobclickAgent.onPageStart/onPageEnd to complete manual PV tracking), if you try to do visualization tracking, the front-end tracking page will prompt the page mismatch.

2. How do I remove the configuration version of the SDK before the publish?

Application environment isolation is often configured in the build.gradle file. Therefore, we recommend that you introduce the tracker-configb package dependency in the debug configuration, but not in the formal release configuration.

Do I support complex custom controls such as ListView,RecycleView, and Fragment?

Yes, you can obtain multiple sets of temporary access credentials at the same time. It should be noted that when setting the unique ID for these controls, you need to set the ID for a specific control in the child item, instead of simply setting the ID for the entire control, such as ViewToos.setViewId(listView, "listViewId").

Valid value

ListView example:

Set the ID in the getView method of the custom ArrayAdapter. For example:

@Override
    public View getView(int position, View convertView, ViewGroup parent) {
        // The logic of the sub-view reuse mechanism.
        View view = convertView;
        if(view == null) {
            LayoutInflater inflater = LayoutInflater.from(mContext);
            View newView = inflater.inflate(R.layout.arrayadapter_item, parent, false);
            view = newView.findViewById(R.id.arrayadapter_text);
        }
        // Update the content of the child view.
        ((TextView)view).setText(data[position]);
        // Set the unique ID. You can set the ID name that has the business meaning. In this example, the text content is directly used.
        ViewTools.setViewId(view, "unified id value", position);

        return view;
    }

Example of RecycleView:

Customize the ViewHolder of RecycleView.Adapter and set the unique ID in the onBindViewHolder method. For example:

@Override
public void onBindViewHolder(final InfoViewHolder holder, int position) {
    if (getItemViewType(position)==TYPE_HEADER) {
        return;
    }
    final int pos=getRealPosition(holder);
    // mData caches network data.
    String title = mData.get(pos).getTitle();
    // Update the title of the TextView. The holder.title is set to TextView.
    holder.title.setText(title);
    // Specify the ID for hodler.title.
    ViewTools.setViewId(holder.title, "Unified ID value", position);
    
}

Customize VideoPlayer:

Locate the control for which you need to set a listener, such as the play button, or the play window, and set the ID

//jzvdStd: the custom video playback control.
// Set the ID for the start button. The ID is the URL.
ViewTools.setViewId(jzvdStd.startButton,"play_"+mData.get(pos).getVideoUrl());
// Set the ID of the playback window.
ViewTools.setViewId(jzvdStd.thumbImageView,"window_"+mData.get(pos).getVideoUrl());

4. How do I record page PVs?

Visualization tracking SDK currently supports the tracking of click and exposure events of controls, but the PV tracking function is not available. The main reason is that the page jump logic of business apps is relatively complex, which may cause errors in page PV records. Therefore, for page pv, we recommend that the business side continue to use the existing code pv tracking.

5. What is the default exposure rule?

The default exposure conditions are:

• Exposure area over /equal to 50% of control area

• Exposure duration over /equal to 500ms

• Merge and send exposure logs

• In a page, if an exposure has already occurred, the exposure is not repeated until the following actions occur:

• Page switching

• Disable the app and re-enter the app

• Back to the background and re-enter the app

[Important] How to define a page?

In Android development, it is customary to define a page with Activity, and the visual tracking SDK also uses Activity to define a page by default. However, in practice, there are often sub-pages in an activity, such as the use of TabHost and Fragment. By default, the SDK will only send exposure records once. Therefore, if the business side needs to switch back and forth between sub-pages under an activity, the exposure needs to be reported again. You can call the exposure data refresh interface to repeat the exposure when the sub-page exits.

6. Can I modify the exposure duration and exposure area baseline in an exposure rule?

This service is not yet available

7. How do I check whether the tracking is normal and whether logs are reported correctly?

In the tracking configuration phase, after you integrate the configuration version SDK, you can click View tracking verification logs on the visualization page to view the tracking and log reporting status in real time.

8. Visualization configuration is no problem, but it is found that click logs cannot be reported in the published APP? (or item items of list in waterfall flow cannot report logs or list sets of lists, and item items of list in layer cannot report logs)

The main reason is that the object with unique ID setting is abnormal. Check the control click event listening logic to check whether the control with the ID bound directly responds to the click. If not, bind the unique ID to the object that responds to the click event.

For example, the layout of items in a common listview is

<relativeLayout clickable="true">
<textview>
</textview>
</relativeLayout>

At this time, the layout object handles the click behavior for the item, and the click event will not be uploaded to the textview object. therefore, if the ID is bound to the textview, the click behavior cannot be captured, and the ID should be bound to the layout object corresponding to the textview accordingly.

For another example, the TextView control needs to set the android:clickable="true" attribute, otherwise TextView can support visual tracking by default, but because it cannot respond to system click events, click logs cannot be reported normally in the released version of App.