Android SDK API

名词约定

名称 解释 备注 极光魔链后台位置
URI Scheme App之间相互调用的入口,且可传递参数。需要在 AndroidManifest.xml 内启动页activity内填写。 例如:mwsdk://,代码内只要填写 mwsdk 即可,注意:首字母不能为数字,不支持大写字母,不支持下划线等特殊字符。 左部导航->“应用设置”->“魔链设置”->“Scheme”
JMLink Key JMLink 的唯一标识。移动端用此来获取 JMLink 具体的 URI Scheme。后台配置 JMLink 时填写 注意与代码内register()第一个参数保持一致。 左部导航->“极光魔链”->”服务管理“->“创建短链”->“短链服务Key”

scheme mlinkkey

Scheme集成

Android系统中App之间是相互隔离的,通过URI Scheme,App之间可以相互调用,并且可以传递参数。

manifest中配置:

<!-- 将“你的Scheme”替换为后台填写的URI Scheme。-->
<activity
    android:name=".WelcomeActivity">
    <intent-filter>
        <data android:scheme="你的Scheme"/>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

支持的版本

applink开始支持的版本 1.2.0

简介

Google Applink 支持Android 6.0及以上版本,用于在短信,备忘录,邮箱等场景一链拉起app,注意部分手手机可能无法支持applink

使用方式

使用applink,需要在后台配置填写应用的签名文件的SHA256值,签名文件的SHA256值可通过以下命令获取,同时客户端manifest需要加入applink相关配置信息

keytool -list -v -keystore 您的签名文件

manifest中配置:

<!-- 将“魔链分配的域名”替换为后台域名管理中支持applink的域名-->
<!-- 如果想为多个域名添加applink,请增加多个intent-filter并修改host>
<activity
    android:name=".WelcomeActivity">
    <intent-filter>
        <data android:scheme="你的Scheme"/>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>

    //applink 配置
     <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="https"
            android:host="魔链分配的域名" />
    </intent-filter>

    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

SDK初始化

支持的版本

开始支持的版本 1.0.0

接口定义

  • JMLinkAPI.getInstance().init(Context context)
    • 接口说明:
      • 初始化接口。建议在Application的onCreate中调用。
    • 参数说明:
      • context:android的上下文
    • 调用示例:
    JMLinkAPI.getInstance().init(this);

SDK设置debug模式

支持的版本

开始支持的版本 1.0.0

接口定义

  • JMLinkAPI.getInstance().setDebugMode(boolean enable)
    • 接口说明:
      • 设置是否开启debug模式。true则会打印更多的日志信息。建议在init接口之前调用。
    • 参数说明:
      • enable:debug开关
    • 调用示例:
    JMLinkAPI.getInstance().setDebugMode(true);

开发者需要注册接收deeplink数据的回调接口

支持的版本

开始支持的版本 1.2.3

接口定义

  • register(JMLinkResponse response)
    • 接口说明:
      • 注册默认路由回调。当下发的jmlink时,将触发此处JMLinkResponse回调。开发者可以在回调中获取参数。 建议程序Application或静态类或onCreate中调用。并且一定要在routerV2()接口前调用
    • 参数说明:
      • response:接口回调
    • 回调说明: response(JMLinkResponseObj obj)
    • 以下为对象中的参数
      • paramMap: 跳转时带的自定义参数map(包含老版本的JMLink中的key)
      • uri:用于跳转的实际uri
      • source:本次JMLink的回调来源,1、Scheme(deeplink/applink),2、Replay(场景还原),3、Unknown(未知来源)
      • type:本次回调类型,1、Installation(安装),2、Open(打开),3、Unknown(未知)
JMLinkAPI.getInstance().register(new JMLinkResponse() {
    @Override
    public void response(JMLinkResponseObj obj) {
           //获取参数,进行后续工作
        Log.e(TAG, "replay = " + obj.paramMap + " " + obj.uri + " " + obj.source + " " + obj.type);
    }
});

具体页面跳转

通过以下接口,可以实现:

  • 通过短链从手机浏览器打开App具体页面(scheme拉起)
  • 借助应用宝,实现从微信内直接打开App具体页面。(如果下载链接是应用宝,建议支持应用宝下载直跳。)
  • App未安装时,通过短链跳转到下载页面,安装后,第一次打开跳转到之前的页面实现场景还原。

scheme拉起时的页面跳转以及场景还原功能

1、通过scheme拉起的应用,在其intent.getData中,会包含拉起时传递过来的uri。拿到这个uri调用router接口即可跳转到指定页面。 2、当scheme不存在时将会使用场景还原功能进行拉取数据。(相当于旧版本的router和replay接口二合一)

支持的版本

开始支持的版本 1.2.3

接口定义

  • JMLinkAPI.getInstance().routerV2(Uri jMLinkUri)
    • 接口说明:
      • 根据应用启动时intent data中带的uri,跳转到具体页面。需要在manifest中配置的scheme接收的activity中调用。并且必须在jmlink key与页面绑定完成之后调用。
      • 当uri不存在时将会使用场景还原功能进行拉取数据
    • 参数说明:
      • jMLinkUri:应用启动时intent data中带的uri
    • 调用示例:

public class WelcomeActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        //首先注册回调接口
        JMLinkAPI.getInstance().register(new JMLinkResponse() {
            @Override
            public void response(JMLinkResponseObj obj) {
            }
        });
        //然后再进行数据路由
        Uri uri = getIntent().getData();
        JMLinkAPI.getInstance().routerV2(uri);
    }
}

是否启用剪切板

为了更好的提高用户跳转体验我们使用到了剪切板功能,开发者可通过此接口来关闭使用剪切板功能

支持的版本

开始支持的版本 1.1.0

接口定义

  • JMLinkAPI.getInstance().enabledClip(boolean clipEnabled)
    • 接口说明:
      • 是否启用剪切板功能,true启用,false不启用,不调用此接口时,默认启用剪切板,如果开发者想关闭则调用此接口关闭,此接口设置不会做持久化处理,每次启动时都需设置,推荐在初始化的时候调用本接口
    • 参数说明:
      • key:是否启用剪切板功能,true启用,false不启用
    • 结果返回:
      • 无返回值
    • 调用示例:
    JMLinkAPI.getInstance().enabledClip(false)

无码邀请

用户A分享App内容给用户B,用户B通过用户A分享的H5页面安装App,则用户A可以累积相应积分,全程无需邀请码。

支持的版本

开始支持的版本 1.0.0

接口定义

  • JMLinkAPI.getInstance().getParam(String key)
    • 接口说明:
      • 从 JS SDK 传递的无码邀请邀请参数信息
    • 参数说明:
      • key:开发者传递的自定义参数的key。比如"u_id"
    • 结果返回:
      • String:自定义参数实际值。如果不存在则返回null
    • 调用示例:
    String uid = JMLinkAPI.getInstance().getParam("u_id");

为了实现从jmlink服务跳转到app指定页面,app端需要通过sdk将jmlink key(portal中创建短链服务时指定),和具体的页面做绑定。具体有两种方法:

一、通过注解绑定(已过期)

支持的版本

开始支持的版本 1.0.0

接口定义

  • JMLinkAPI.getInstance().registerWithAnnotation()
    • 接口说明:
      • 开启注解绑定功能。调用之后sdk会将所有标注了JMLinkRouter注解的类与jmlink key做绑定。 建议在Application类sdk init之后调用。
    • 调用示例:
//开启注解绑定
public class JMLinkExampleApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        JMLinkAPI.getInstance().setDebugMode(true);
        JMLinkAPI.getInstance().init(getApplicationContext());
        JMLinkAPI.getInstance().registerWithAnnotation();//开启注解绑定
    }
}

//注册默认路由,当下发的jmlink key没有与任何页面绑定时,跳转到此页面
@JMLinkDefaultRouter
public class DefaultRouteActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setTitle("DefaultRouteActivity");
    }

}

//注册路由,当下发的jmlink key与此处的“jmlink_key”一致时,跳转到此页面。checkYYB状态后,应用宝可通过此方法获取参数信息
@JMLinkRouter(keys = "jmlink_key")
public class SecondActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setTitle("SecondActivity");

        //通过intent方式获取动态参数值
        Intent intent = getIntent();
        if (intent != null) {
            String param = intent.getStringExtra("param");
        }
    }
}

注意:如果有 Fragment 作为页面,您需要跳转到具体Fragment时,您可能需要:
① 在 JMLink 的动态参数添加type来区别是哪个 Fragment
② 在它的 FragmentActivity 内添加注解,然后根据type判断具体跳转到哪个 Fragment。

二、通过接口动态绑定(已过期)

除了registerWithAnnotation(),我们还提供register()。方便开发者在跳转前处理一些额外动作,比如登录等。 如跳转前需要登录等,可用下面的register方法

支持的版本

开始支持的版本 1.0.0

接口定义

  • JMLinkAPI.getInstance().registerDefault(JMLinkCallback callback)

    • 接口说明:
      • 注册默认路由回调。当下发的jmlink key没有任何页面匹配时,将触发此处JMLinkCallback回调。开发者可以在回调中触发实际页面的跳转。 建议程序启动页面onCreate中调用。并且一定要在router()接口前调用
    • 参数说明:
      • callback:接口回调
    • 回调说明: execute(Map paramMap, Uri uri)
      • paramMap: 跳转时带的自定义参数map
      • uri:用于跳转的实际uri
  • JMLinkAPI.getInstance().register(String jmlinkKey, JMLinkCallback callback)

    • 接口说明:
      • 针对指定jmlink key注册路由回调。当下发的jmlink key与此处指定的jmlinkKey匹配时,将触发此处JMLinkCallback回调。开发者可以在回调中触发实际页面的跳转。 建议程序启动页面onCreate中调用。并且一定要在router()接口前调用
    • 参数说明:
      • jmlinkKey:jmlink 的 key,jmlink的唯一标识
      • callback:接口回调
    • 回调说明: execute(Map paramMap, Uri uri)
      • paramMap: 跳转时带的自定义参数map
      • uri:用于跳转的实际uri
  • JMLinkAPI.getInstance().unregisterDefault()

    • 接口说明:
      • 反注册默认路由,执行该方法会删除已注册的默认路由,由于注册默认路由时JMLinkCallback中可能包含当前界面的引用,如果不进行反注册回收的话,可能发生内存泄露,可在onDestroy中执行本方法进行反注册。
  • JMLinkAPI.getInstance().unregister(String jmlinkKey)

    • 接口说明:

      • 反注册指定jmlinkKey的路由回调,执行该方法会删除已注册的针对指定jmlink key注册的路由回调,由于注册路由时JMLinkCallback中可能包含当前界面的引用,如果不进行反注册回收的话,可能发生内存泄露,可可在onDestroy中执行本方法进行反注册。
    • 调用示例:


@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    register (this);
}
private void register(Context context){
    JMLinkAPI.getInstance().registerDefault(new JMLinkCallback() {
        @Override
        public void execute(Map<String, String> paramMap, Uri uri) {
            JMLinkIntentBuilder.buildIntent(paramMap, context, DefaultRouteActivity.class);
        }
   });
    // jmlinkKey:  jmlink 的 key, jmlink的唯一标识
   JMLinkAPI.getInstance().register("您的jmlinkKey", new JMLinkCallback() {
        public void execute(Map<String, String> paramMap, Uri uri) {
            JMLinkIntentBuilder.buildIntent(paramMap, context, SecondActivity.class);
        }
    });
}

private static void unregister() {
     JMLinkAPI.getInstance().unregisterDefault();
     JMLinkAPI.getInstance().unregister("您的jmlinkKey")
}

@Override
protected void onDestroy() {
    super.onDestroy();
    unregister();
}

或者使用静态类实现JMLinkCallback

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    register();
}

private void register(){
    JMLinkAPI.getInstance().registerDefault(new DefaultCallback(getApplicationContext()));
    // jmlinkKey:  jmlink 的 key, jmlink的唯一标识
    JMLinkAPI.getInstance().register("您的jmlinkKey", new KeyCallback(getApplicationContext()));
}

static class DefaultCallback implements JMLinkCallback {
    private Context context;
    public DefaultCallback(Context context) {
        this.context = context;
    }
    @Override
    public void execute(Map<String, String> paramMap, Uri uri) {
        JMLinkIntentBuilder.buildIntent(paramMap, context, DefaultRouteActivity.class);
    }
}

static class KeyCallback implements JMLinkCallback {
    private Context context;
    public KeyCallback(Context context) {
        this.context = context;
    }

    @Override
    public void execute(Map<String, String> paramMap, Uri uri) {
        JMLinkIntentBuilder.buildIntent(paramMap, context, SecondActivity.class);
    }
}

三、推荐做法(已过期)

如果业务简单且变化较小可以使用上述两种方式绑定JMLink key,如果业务复杂有多个短链和JMLink key,推荐直接使用动态注册registerDefault的方式,开发者可根据自己的业务设计参数协议,在registerDefault的回调中通过获取的参数来判断跳转哪个页面,而不使用JMLink key

具体页面跳转(已过期)

通过以下接口,可以实现:

  • 通过短链从手机浏览器打开App具体页面(scheme拉起)
  • 借助应用宝,实现从微信内直接打开App具体页面。(如果下载链接是应用宝,建议支持应用宝下载直跳。)
  • App未安装时,通过短链跳转到下载页面,安装后,第一次打开跳转到之前的页面实现场景还原。

一、通过scheme拉起时的页面跳转(已过期)

通过scheme拉起的应用,在其intent.getData中,会包含拉起时传递过来的uri。拿到这个uri调用router接口即可跳转到指定页面。

支持的版本

开始支持的版本 1.0.0

接口定义

  • JMLinkAPI.getInstance().router(Uri jMLinkUri)
    • 接口说明:
      • 根据应用启动时intent data中带的uri,跳转到具体页面。需要在manifest中配置的scheme接收的activity中调用。并且必须在jmlink key与页面绑定完成之后调用。
    • 参数说明:
      • jMLinkUri:应用启动时intent data中带的uri
    • 调用示例:

public class WelcomeActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        JMLinkAPI.getInstance().registerWithAnnotation();
        Uri uri = getIntent().getData();
        if (uri != null) { //uri不为null,表示应用是从scheme拉起
            JMLinkAPI.getInstance().router(uri);
            finish();
        }
    }
}

二、场景还原(已过期)

在intent.getData中,没有任何uri相关信息时我们需要调用replay接口进行场景还原跳转到之前的浏览的具体页面,常见场景为以下两种:

  • 被应用宝或者launcher等其他场景拉起的应用
  • App未安装时,通过短链跳转到下载页面。安装后,第一次打开App

注意1.1.0开始新增接口replay进行应用宝和安装时的场景还原,原有应用宝和场景还原的接口deferredRouter和checkYYB被标记过期用replay替换,注意在一个页面中只需调用一次replay(ReplayCallback replayCallback),如果开发者之前使用的版本低于1.1.0且在一个页面中先后调用了deferredRouter和checkYYB,则升级上来后去掉deferredRouter()的调用将checkYYB替换成replay即可

支持的版本

开始支持的版本 1.1.0

接口定义

  • JMLinkAPI.getInstance().replay(ReplayCallback replayCallback)
    • 接口说明:
      • 在intent.getData没有uri相关信息时调用,会去检查是否来自应用宝或者安装场景还原,如果是则跳转至目标页面.须在jmlink key与页面绑定完成之后调用
    • 参数说明:
      • replayCallback: 回调接口
    • 回调说明:
      onSuccess()
      跳转到具体页面成功时触发。
      onFail()
      跳转到具体页面失败时触发。
public class JMLinkExampleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        JMLinkAPI.getInstance().setDebugMode(true);
        JMLinkAPI.getInstance().init(getApplicationContext());
        JMLinkAPI.getInstance().registerDefault(new JMLinkCallback() {
            @Override
            public void execute(Map<String, String> paramMap, Uri uri) {
                //执行跳转逻辑
            }
        });
    }
}

public class WelcomeActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Uri uri = getIntent().getData();
        Log.e(TAG, "data = " + uri);
        if (uri != null) {
            JMLinkAPI.getInstance().router(uri);
            finish();
        } else {
            JMLinkAPI.getInstance().replay(new MyReplayCallback(this));
        }
    }

    static class MyReplayCallback implements ReplayCallback {
        Context context;
        WeakReference<Activity> weakReference;
        MyReplayCallback(Activity activity) {
            context = activity.getApplicationContext();
            weakReference = new WeakReference<>(activity);
        }
        @Override
        public void onFailed() {
            Log.d(TAG, "replay failed");
            Intent intent = new Intent(context, DefaultRouteActivity.class);
            intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TOP);
            context.startActivity(intent);
            Activity activity = weakReference.get();
            if (activity != null) {
                activity.finish();
            }
        }

        @Override
        public void onSuccess() {
            Log.d(TAG, "replay success");
            Activity activity = weakReference.get();
            if (activity != null) {
                Log.d(TAG, "activity finish");
                activity.finish();
            }
        }
    }
}


Copyright 2011-2020, jiguang.cn, All Rights Reserved.
粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

Documentation built with MkDocs.