メインコンテンツまでスキップ

Mobage Android NativeSDK Quick Guide

本文环境设置和示例代码基于:

  • Eclipse Juno Service Release 2
  • Mobage Android SDK 1.3.6
  • Android 4.2.2
  • Java 1.6.0_65

1 前期准备

要使用 Mobage Android SDK 进行开发需要进行必要的前期准备。

1.1 注册成为DeNA开发者​

访问 DeNA 开发者论坛 https://developer.mobage.cn/v/ 。根据提示注册新的用户,完成后通过登陆开发者网站。

1.2 注册应用程序​

输入相应信息后点击确认,在确认页面点击提交。跳转到应用程序详细。

 

1.3 获得客户端用key、secret​

选中左侧应用基本信息中的Android Tab,其中的SDK Consumer Key、Secret将会在后面开发中用于接入SDK,在未半公开的情况下,只能使用Sandbox环境。

ヒント

基本信息Tab中的key和secret是服务器端使用,不要和图中客户端SDK用的搞混了。

2 Eclipse相关设定

本章说明Eclipse中的设定方法。

2.1 导入lib工程​

选择文件->导入,导入lib工程Android/MobageNativeSDKLib。

2.2 建立依赖关系​

  1. 在开发的工程点击右键选择属性,在属性界面选择“Android”
  2. 在Android面板下侧点击“Add”,选择刚才导入的lib工程,点击“OK”

2.3 AndroidManifest.xml中的权限、Activity、Service、Receiver设定​

由于每个SDK版本中的该文件的设定有可能不太一样,请参考SDK文档(目录Android/docs/pdf)中章节“权限设定”和“Activity的设定”。

2.4 关于res/xml下的文件​

在引用了lib项目Android/MobageNativeSDKLib之后,会看到这个lib项目下的res/xml下有三个xml文件:mobage_init.xml, mobage_alliance.xml, mobage_market.xml。 这三个文件保持默认就可以了,在开发者打包上传到开发者平台之后,平台会自动的解包,然后根据不同的环境(SANDBOX、PRODUCTION),不同的渠道,往这三个文件分别写入不同的值,再重新打包成相应版本。

当然,开发者如果调试的时候需要切换环境的话,也可以自己修改mobage_init.xml,来切换SANDBOX和PRODUCTION。

3 Mobage平台初始化

 要完成Mobage平台初始化,请在onCreate中依次完成如下步骤。

3.1 注册资源​

Mobage.registerMobageResource(this, getPackageName() + ".R");

3.2 设定应用程序的consumer key 及sonsumer secret​

替换下面代码中的${APP_ID},${SANDBOX_KEY}, ${SANDBOX_SECRET},  ${PRODUCTION_KEY},  ${PRODUCTION_SECRET} (在步骤1.3中获取)

try {
ServerMode serverMode = Mobage.getPlatformEnvironment(mActivity,
R.xml.mobage_init);
if (serverMode == ServerMode.SANDBOX) {
Mobage.initialize(Mobage.Region.CN, Mobage.ServerMode.SANDBOX,
"${SANDBOX_KEY}",
"${SANDBOX_SECRET}", "${APP_ID}",
activity);
} else if (serverMode == ServerMode.PRODUCTION) {
Mobage.initialize(Mobage.Region.CN,
Mobage.ServerMode.PRODUCTION, "${PRODUCTION_KEY}",
"${PRODUCTION_SECRET}", "${APP_ID}",
activity);
}
} catch (NameNotFoundException e) {
e.printStackTrace();
} catch (ClassNotFoundException e) {
e.printStackTrace();

} catch (XmlPullParserException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
}

3.3 实现并注册PlatformListener​

PlatformListener 是用于监听梦宝谷平台如登录,账号切换等事件的监听器。开发者至少应该在
主 Activity 中实现该监听器并使用 Mobage.addPlatformListener(PlatformListenerplatformListener)方法将其注册至 SDK 中。其中, 开发者仅且必须在主 Activity 的 PlatformListener 的 onLoginComplete(登录完成)的事件中调用 Mobage.registerTick()方法。onSwitchAccount 事件发生在用户切换平台账号完成时,此时开发 者需要重新启动游戏或关闭游戏以便使切换的新账户生效。onDashboardClose 事件发生在用户退 出社区页面时。具体代码如下:

Mobage.addPlatformListener(new PlatformListener() {
@Override
public void onDashboardClose() {
//

}

@Override
public void onLoginCancel() {
//

}

@Override
public void onLoginComplete(String arg0) {
// 登陆成功之后会进入该回调,参数是用户的id
Mobage.registerTick();
}

@Override
public void onLoginError(Error arg0) {
// 登陆发生错误,进入这个回调
Mobage.checkLoginStatus();

}

@Override
public void onLoginRequired() {
//

}

@Override
public void onSplashComplete() {
// Mobage启动画面结束进入该回调。
Mobage.hideSplashScreen();
}

@Override
public void onSwitchAccount() {
// 切换账号功能整个Mobage社区统一,用户在进入社区的个人主页里面进行账号切换。
// 如果切换账号成功,则会进入这个回调函数。开发者需要在这个回调函数里面结束应用程序,这样下次登陆新账号才会生效。
//mActivity.finish();
}

@Override
public void onUserFreeze() {
// 冻结用户回调函数。
// Please finish all your activities here
//mActivity.finish();

});  

3.4 登陆及检查登陆状态​

在进入游戏时需要使用 Mobage.checkLoginStatus()方法检查登录状态

Mobage.checkLoginStatus();

3.5 添加Mobage的生命周期​

除了以上的初始化过程,开发者还需要在应用程序的所有 Activity 中在不同的生命周期的相应方 法中调用相应的 SDK 方法,具体如下:

@Override
public void onCreate(){
super.onCreate();
//Mobage的初始化代码
Mobage.onCreate();
}

@Override
public void onPause() {
super.onPause();
Mobage.onPause();
}

@Override
public void onResume() {
Mobage.setCurrentActivity(this);
super.onResume();
Mobage.onResume();
}

@Override
public void onRestart() {
super.onRestart();
Mobage.onRestart();
}

@Override
public void onStop() {
super.onStop();
}

@Override
public void onDestroy() {
super.onDestroy();
Mobage.onStop();
}
備考

注意

由于Mobage.onStop做了一些清除操作,所以如果是多个activity的话,只能在最后退出游戏的那个activity的onDestroy方法中调用,保证只调用了一次。

3.1到3.5章节的完整示例代码如下:

public class MainActivity extends Activity {
private static final String TAG = "MainActivity";
private PlatformListener mPlatformListener;
private static final String APPID = "13000057";
private static final Mobage.Region REGION = Mobage.Region.CN; // 简体平台CN,繁体平台TW
private static final String SDK_SANDBOX_KEY = "sdk_app_id:13000057";
private static final String SDK_PRODUCTION_KEY = "sdk_app_id:13000057";
private static final String SDK_SANDBOX_SECRET = "a08e2b8d7e70b26223cff0982f7e8dc1";
private static final String SDK_PRODUCTION_SECRET = "893a0ace96b5654a8492eb4ee15c404a";

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

@SuppressWarnings("unused")
Context context = getApplication().getApplicationContext();
CookieSyncManager.createInstance(this);

Mobage.registerMobageResource(this, getPackageName() + ".R");
setContentView(R.layout.activity_main);
initCN();
createPlatformListener();
Mobage.addPlatformListener(mPlatformListener);
Mobage.checkLoginStatus();
Mobage.onCreate();
}

@Override
public void onPause() {
Log.e(TAG, "onPause called");
super.onPause();
Mobage.onPause();
}

@Override
public void onResume() {
Log.e(TAG, "onResume called");
Mobage.setCurrentActivity(this);
super.onResume();
Mobage.onResume();
}

@Override

public void onStop() {
Log.e(TAG, "onStop called");
super.onStop();
}

@Override
public void onDestroy() {
Log.e(TAG, "onDestroy called");
super.onDestroy();
Mobage.onStop();
}

@Override
public void onRestart() {
Log.e(TAG, "onRestart called");
super.onRestart();
Mobage.onRestart();
}

@Override
public void onConfigurationChanged(Configuration newConfig) {
super.onConfigurationChanged(newConfig);
}

private void initCN() {
try {
ServerMode serverMode = Mobage.getPlatformEnvironment(this, R.xml.mobage_init);
if (serverMode == ServerMode.SANDBOX) {
Mobage.initialize(REGION, Mobage.ServerMode.SANDBOX, SDK_SANDBOX_KEY, SDK_SANDBOX_SECRET, APPID, this);
} else if (serverMode == ServerMode.PRODUCTION) {
Mobage.initialize(REGION, Mobage.ServerMode.PRODUCTION, SDK_PRODUCTION_KEY, SDK_PRODUCTION_SECRET, APPID, this);
}
} catch (NameNotFoundException e) {
e.printStackTrace();
} catch (ClassNotFoundException e) {
e.printStackTrace();
} catch (XmlPullParserException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
}
}

public void createPlatformListener() {
if (mPlatformListener != null) {
return;
}

mPlatformListener = new PlatformListener() {

boolean mSplashCompleted = false;
boolean mLoginCompleted = false;

boolean checkComplete() {
return mSplashCompleted && mLoginCompleted;
}

void onCompleted() {
mSplashCompleted = false;
mLoginCompleted = false;

Mobage.hideSplashScreen();
}

public void onLoginComplete(String userId) {
Log.i(TAG, "Login completed:" + userId);
mLoginCompleted = true;
Mobage.registerTick();
if (checkComplete()) {
onCompleted();
}
}

public void onLoginRequired() {
Log.i(TAG, "Login required.");
}

public void onLoginError(Error error) {
Log.e(TAG, "Login failed. " + error.toString());
Mobage.checkLoginStatus();
}

@Override
public void onSplashComplete() {
Log.e(TAG, "splash complete!.");
mSplashCompleted = true;

if (checkComplete()) {
onCompleted();
}

}

@Override
public void onLoginCancel() {
}

@Override
public void onSwitchAccount() {
MainActivity.this.finish();
}

public void onDashboardClose() {
Toast.makeText(MainActivity.this, "已退出社区", Toast.LENGTH_LONG).show();
}

@Override
public void onUserFreeze() {
MainActivity.this.finish();
}
};

}

}

至此,该项目已经可以编译运行,用户可以登陆进Mobage平台了。

4 Mobage功能接入

4.1 交易​

 

Mobage平台有统一的货币—M币,用户在社区用支付宝,财付通等方式将人民币充值成M币。对于充值M币这个流程,SDK用webview实现,整个平台是统一的,不需要开发商再做额外的接入。而开发商需要实现的是用M币来购买游戏内道具的流程。

mobage提供3种流程,详细流程可以参考(https://docs.mobage.com/display/CNSPAPP/How+to+use+bank+and+eco+native), 如果只是简体平台和繁体平台,并没有海外平台的计划,则推荐使用第一种流程接入,这里介绍一下第一种流程的大致步骤:

 

(1)先到开发者网站注册道具信息,

(2)在游戏控制台 - 2其他功能追加 - Bank回调设置中设置该应用的回调地址,用于接收交易完成之后Mobage发出的Http请求,以通知游戏服务器交易完成。(该步骤可选,如未登记回调地址则不会调用。)

 

(2)按create->open->close的顺序在createTransaction的onSuccess回调函数里面调用openTransaction, 在openTransaction的onSuccess回调函数里面调用closeTransaction,注意交易必须成功close交易才算完成。虽然在openTransaction的时候已经扣费,但是如果没有close,10分钟之后交易会被自动cancel并将扣除的M币返回给用户账号。

 

(3)在close之后Mobage平台会向登记的回调地址发送http请求,开发者需要对该请求进行处理。详情参考https://docs.mobage.com/display/CNSPAPP/Callback+function+description

示例代码:

public void purchaseGameItemsProcess() {
createTransaction();
}


private void createTransaction() {
ArrayList<BillingItem> items = new ArrayList<BillingItem>();
BillingItem item = new BillingItem();
ItemData data = new ItemData();
data.setId("Your item id"); //设置在开发者网站注册的道具id
item.setItem(data);
item.setQuantity(1);//要购买的数量
items.add(item);

//comment for this transaction
String comment = "no comment";
Debit.createTransaction(items, comment,
new OnProcessTransactionWithDialogComplete() {

@Override
public void onSuccess(Transaction transaction) {
openTransaction(transaction.getId());
}

@Override
public void onError(Error error) {
}

@Override
public void onCancel() {
}

});

}



private void openTransaction(String mTransactionId) {
Log.v(TAG, "begin OpenTransaition");

Debit.openTransaction(mTransactionId,
new OnProcessTransactionComplete() {

@Override
public void onSuccess(Transaction transaction) {
closeTransaction(transaction.getId());
}

@Override
public void onError(Error error) {

}

});

}


private void closeTransaction(String mTransactionId) {
Log.v(TAG, "begin CloseTransaition");

Debit.closeTransaction(mTransactionId,
new OnProcessTransactionComplete() {

@Override
public void onSuccess(Transaction transaction) {

}

@Override
public void onError(Error error) {

}
});

}

 

4.2 其他API​

 关于其他API,可参考随SDK附带的示例代码及文档。

5 导出apk包

5.1 修改包名​

由于Mobage有统一的命名规范,请在打包前按规则重命名,

简体平台格式:cn.mobage.g${APP_ID}, 用自己游戏的appid替换${APP_ID}。例如,cn.mobage.g13000057

繁体平台格式:   tw.mobage.g${APP_ID}, 用自己游戏的appid替换${APP_ID}。例如,tw.mobage.g23000013。

重命名的方法:

  1. 点击项目的右键,Android Tools -> Rename Application Package
  2. 输入新的包名,并点击“OK”
  3. eclipse 会弹出一个对话框,显示一些将要被更新的文件,保持默认,你只需要点击“Finish"就重命名好了。

5.2 代码混淆 (可选)​

如果开发者需要对代码进行混淆,针对mobage的代码进行混淆的方法:

  1. 在项目里添加一个文件,比如proguard.txt。

  2. 在该文件中添加如下内容,如果有其他的第三方的代码需要混淆,可以参考混淆的规则添加相应代码:

    -keep class **.R$* { *; }
    -keep class **.R
    -keep class **.R$* {
    <fields>;
    }
    -keepattributes Signature
    -keepattributes *Annotation*
    -keepattributes InnerClasses
    -keep class com.alipay.android.app.** {*;}
    -keep class com.huawei.cloudplus.pay.** {*;}
    -keep class com.yeepay.android.plugin.** {*;}
    -keep class com.novell.sasl.client.** {*;}
    -keep class de.measite.smack.** {*;}
    -keep class org.apache.** {*;}
    -keep class org.jivesoftware.smack.** {*;}
    -keep class com.aspire.vending.** {*;}
    -keep class com.ccit.wlan.** {*;}
    -keep class mm.vending.** {*;}
    -keep class com.android.vending.billing.** {*;}
    -keep class com.denachina.** {*;}
    -keep class com.mobage.android.** {*;}
    -keep class jp.dena.mobage.android.** {*;}

    -dontwarn com.alipay.android.app.**
    -dontwarn com.huawei.cloudplus.pay.**
    -dontwarn com.yeepay.android.plugin.**
    -dontwarn com.novell.sasl.client.**
    -dontwarn de.measite.smack.**
    -dontwarn org.apache.**
    -dontwarn org.jivesoftware.smack.**
    -dontwarn com.aspire.vending.**
    -dontwarn com.ccit.wlan.**
    -dontwarn mm.vending.**
    -dontwarn com.android.vending.billing.**
    -dontwarn com.denachina.**
    -dontwarn com.mobage.android.**
    -dontwarn jp.dena.mobage.android.**
  3. 在project.properties添加一项proguard.config,指向刚才定义的proguard.txt文件,比如:

    proguard.config=${sdk.dir}/tools/proguard/proguard-android.txt:proguard.txt

5.3 导出未签名的apk​

点击项目右键,Anroid Tools -> Export unsigned Application Package

5.4 签名​

如果您还没有keystore文件,先用keytool生成:

格式:keytool -genkey -v -keystore ${YOUR_KEY_STORE_FILE} -alias ${YOUR_KEY_STORE_ALIAS} -keyalg ${ALGORITHM} -validity ${VALID_DAYS}

例子:keytool -genkey -v -keystore test.keystore -alias test.keystore -keyalg RSA -validity 1000

替换命令中的参数,输入密码等信息即可生成keystore文件:

${YOUR_KEY_STORE_FILE}: 生成的keystore文件

${YOUR_KEY_STORE_ALIAS}: 生成的keystore别名

 ${ALGORITHM}: 加密和数字签名的算法

${VALID_DAYS}: 有效天数

然后使用如下命令对刚导出的包进行签名:

jarsigner -verbose -keystore ${YOUR_KEY_STORE_FILE}  -signedjar ${APK_FILENAME_AFTER_SIGN}  ${APK_FILENAME_BEFORE_SIGN} ${YOUR_KEY_STORE_ALIAS}

请替换命令中的参数,回车输入密码后即可签名成功。

${APK_FILENAME_BEFORE_SIGN}:签名前的名字,

${APK_FILENAME_AFTER_SIGN}:签名后的名字,

 ${YOUR_KEY_STORE_FILE}:你的keystore文件

${YOUR_KEY_STORE_ALIAS}: 你的keystore文件别名

5.5 zipalign优化(可选)​

由于在上传到开发者平台之后,平台会解包再重新打包,重新打包的时候也会进行zipalign优化,所以这不是一个必做步骤。zipalign优化的命令:

zipalign -v 4 source.apk destination.apk    (source.apk是优化前的名字,destination.apk是优化后的名字)