Android SDK API
名词约定
名称 | 解释 | 备注 | 极光魔链后台位置 |
---|---|---|---|
URI Scheme | App 之间相互调用的入口,且可传递参数。需要在 AndroidManifest.xml 内启动页 activity 内填写。 | 例如:mwsdk://,代码内只要填写 mwsdk 即可,注意:首字母不能为数字,不支持大写字母,不支持下划线等特殊字符。 | 左部导航->“应用设置”->“魔链设置”->“Scheme” |
JMLink Key | JMLink 的唯一标识。移动端用此来获取 JMLink 具体的 URI Scheme。后台配置 JMLink 时填写 | 注意与代码内 register()第一个参数保持一致。 | 左部导航->“极光魔链”->”服务管理“->“创建短链”->“短链服务 Key” |
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 集成
支持的版本
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);
JMLink 注册 deeplink 回调
开发者需要注册接收 deeplink 数据的回调接口
支持的版本
开始支持的版本 1.2.3
接口定义
- register(JMLinkResponse response)
- 接口说明:
- 注册默认路由回调。当下发的 jmlink 时,将触发此处
JMLinkResponse
回调。开发者可以在回调中获取参数。 建议程序 Application 或静态类或 onCreate 中调用。并且一定要在 routerV2()接口前调用
- 注册默认路由回调。当下发的 jmlink 时,将触发此处
- 参数说明:
- 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);
}
}
无码邀请
用户 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 key 与页面绑定(已过期)
为了实现从 jmlink 服务跳转到 app 指定页面,app 端需要通过 sdk 将 jmlink key(portal 中创建短链服务时指定),和具体的页面做绑定。具体有两种方法:
一、通过注解绑定(已过期)
支持的版本
开始支持的版本 1.0.0
接口定义
- JMLinkAPI.getInstance().registerWithAnnotation()
- 接口说明:
- 开启注解绑定功能。调用之后 sdk 会将所有标注了
JMLinkRouter
注解的类与 jmlink key 做绑定。 建议在 Application 类 sdk init 之后调用。
- 开启注解绑定功能。调用之后 sdk 会将所有标注了
- 调用示例:
- 接口说明:
//开启注解绑定
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()接口前调用
- 注册默认路由回调。当下发的 jmlink key 没有任何页面匹配时,将触发此处
- 参数说明:
- callback:接口回调
- 回调说明: execute(Map<String, String> paramMap, Uri uri) + paramMap: 跳转时带的自定义参数 map + uri:用于跳转的实际 uri
- 接口说明:
JMLinkAPI.getInstance().register(String jmlinkKey, JMLinkCallback callback)
- 接口说明:
- 针对指定 jmlink key 注册路由回调。当下发的 jmlink key 与此处指定的 jmlinkKey 匹配时,将触发此处
JMLinkCallback
回调。开发者可以在回调中触发实际页面的跳转。 建议程序启动页面 onCreate 中调用。并且一定要在 router()接口前调用
- 针对指定 jmlink key 注册路由回调。当下发的 jmlink key 与此处指定的 jmlinkKey 匹配时,将触发此处
- 参数说明:
- jmlinkKey:jmlink 的 key,jmlink 的唯一标识
- callback:接口回调
- 回调说明: execute(Map<String, String> 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();
}
}
}
}