1. 初始化（在 Application.onCreate 中）

import com.umeng.commonsdk.deeplink.UMCommonDeepLink;
import com.umeng.commonsdk.deeplink.UMCommonDeepLinkCallback;

// 注册 handleOpenURL 回调（可选，仅拉活场景需要）
UMCommonDeepLink.getInstance().setCallback(new UMCommonDeepLinkCallback() {
    @Override
    public void onResolveDeepLink(Map<String, Object> params) {
        // params 包含:
        //   "install_params" → Map<String, String> (URL query 参数)
        //   "install_path"   → String (URL path)
        Log.d("DeepLink", "拉活参数: " + params);
    }
}, null); // handler 传 null 表示回调到主线程

2. 拉活传参（在 Activity.onCreate / onNewIntent 中）

import com.umeng.commonsdk.deeplink.UMCommonDeepLink;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // 从 Intent 中获取拉活 URI
    Uri uri = getIntent().getData();
    if (uri != null) {
        boolean handled = UMCommonDeepLink.getInstance().handleOpenURL(this, uri);
        // handled=true 表示 URL 中包含归因参数，已触发回调和上报
    }
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    Uri uri = intent.getData();
    if (uri != null) {
        UMCommonDeepLink.getInstance().handleOpenURL(this, uri);
    }
}

3. DDL 延迟深链还原

import com.umeng.commonsdk.deeplink.UMCommonDeepLink;
import com.umeng.commonsdk.deeplink.InstallParamsCallback;

UMCommonDeepLink.getInstance().getInstallParams(this, null, new InstallParamsCallback() {
    @Override
    public void onSuccess(Map<String, Object> params) {
        // params 包含:
        //   "install_params" → Map<String, String> (服务端返回的安装归因参数)
        //   "install_path"   → String (广告目标页路径)
        String targetPath = (String) params.get("install_path");
        Log.d("DeepLink", "DDL 还原成功, targetPath=" + targetPath);
    }

    @Override
    public void onFailure(int errorCode, String errorMsg) {
        // errorCode: -1~-5，详见"错误码"章节
        Log.w("DeepLink", "DDL 失败: code=" + errorCode + ", msg=" + errorMsg);
    }
});

4. 剪切板归因

请在 UMConfigure.init() 完成后读取剪切板内容，并将读取结果传给 handlePasteboardURL()。SDK 不会主动读取系统剪切板。如需获取解析后的深链参数，请沿用前文方式提前调用 setCallback()。

import android.content.ClipData;
import android.content.ClipboardManager;
import android.content.Context;

import com.umeng.commonsdk.deeplink.UMCommonDeepLink;

ClipboardManager clipboard =
        (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);

if (clipboard != null && clipboard.hasPrimaryClip()) {
    ClipData clipData = clipboard.getPrimaryClip();
    if (clipData != null && clipData.getItemCount() > 0) {
        CharSequence text = clipData.getItemAt(0).getText();
        if (text != null) {
            boolean handled = UMCommonDeepLink.getInstance()
                    .handlePasteboardURL(this, text.toString().trim());
            if (handled) {
                // 内容已进入归因处理流程
            }
        }
    }
}

剪切板归因与 handleOpenURL() 共用通过 setCallback() 注册的 UMCommonDeepLinkCallback。已注册回调时，识别成功后 SDK 会通过指定的 Handler 投递 onResolveDeepLink()；Handler 传 null 时在主线程回调：

import com.umeng.commonsdk.deeplink.UMCommonDeepLinkCallback;
import java.util.Map;

UMCommonDeepLink.getInstance().setCallback(new UMCommonDeepLinkCallback() {
    @Override
    public void onResolveDeepLink(Map<String, Object> params) {
        Map<String, String> queryParams =
                (Map<String, String>) params.get("install_params");
        String path = (String) params.get("install_path");
        navigateToPage(path, queryParams);
    }
}, null);

5. 获取归因结果

请在主进程的 Application.onCreate() 中、调用 UMConfigure.init() 之前注册归因结果监听器。SDK 初始化完成后会自动查询服务端归因结果。

import com.umeng.commonsdk.UMConfigure;
import com.umeng.commonsdk.deeplink.OnAttributionListener;

import android.util.Log;
import org.json.JSONObject;

UMConfigure.setOnAttributionListener(new OnAttributionListener() {
    @Override
    public void onAttributionSuccess(JSONObject attribution) {
        // 归因查询成功，attribution 为服务端返回的归因结果
        Log.d("Attribution", "归因结果: " + attribution);
    }

    @Override
    public void onAttributionFail(int errorCode) {
        // 当前 errorCode 为 -1，表示未获得有效归因结果
        Log.w("Attribution", "归因查询失败: " + errorCode);
    }
});

UMConfigure.init(this, "YOUR_APPKEY", "channel",
        UMConfigure.DEVICE_TYPE_PHONE, null);

UMCommonDeepLink

门面单例类，通过 UMCommonDeepLink.getInstance() 获取实例。

public static UMCommonDeepLink getInstance()

public void setCallback(UMCommonDeepLinkCallback callback, Handler handler)

public void getInstallParams(Context ctx, Handler handler, InstallParamsCallback callback)

public boolean handleOpenURL(Context ctx, Uri uri)
public boolean handleOpenURL(Context ctx, String url)

public boolean handlePasteboardURL(Context ctx, String urlString)

public static void setOnAttributionListener(OnAttributionListener listener)

OnAttributionListener

public interface OnAttributionListener {
    void onAttributionSuccess(JSONObject attribution);
    void onAttributionFail(int errorCode);
}

成功结果可能包含 appkey、umid、channel、attributionId、attributionType、strategy、attributionTime 等字段，实际字段及取值以服务端返回为准。所有回调均异步投递到主线程。

UMCommonDeepLinkCallback

public interface UMCommonDeepLinkCallback {
    void onResolveDeepLink(Map<String, Object> params);
}

handleOpenURL 命中归因参数时的回调接口。handleOpenURL未命中归因返回false则不会回调。

params 字段说明:

InstallParamsCallback

public interface InstallParamsCallback {
    void onSuccess(Map<String, Object> params);
    void onFailure(int errorCode, String errorMsg);
}

getInstallParams 的结果回调接口。

onSuccess params 字段说明: