以下关于文件的阐述以及代码的样例,均以 PHP 程序为例。

UCenter 的 API 接口文件必须存放于应用程序根目录的“api/”目录中,且文件名必须为 uc.php,即“api/uc.php”。文件结构可分为 4 部分,包含 12 个接口项目。第 1 部分为常量定义,第 2 部分为初始化输入参数、第 3 部分为接口代码段、第 4 部分为函数定义。

1、常量定义

define('UC_VERSION', '1.0.0');		//UCenter 版本标识

define('API_DELETEUSER', 1);		//用户删除 API 接口开关
define('API_RENAMEUSER', 1);		//用户改名 API 接口开关
define('API_UPDATEPW', 1);		//用户改密码 API 接口开关
define('API_GETTAG', 1);		//获取标签 API 接口开关
define('API_SYNLOGIN', 1);		//同步登录 API 接口开关
define('API_SYNLOGOUT', 1);		//同步登出 API 接口开关
define('API_UPDATEBADWORDS', 1);	//更新关键字列表 开关
define('API_UPDATEHOSTS', 1);		//更新域名解析缓存 开关
define('API_UPDATEAPPS', 1);		//更新应用列表 开关
define('API_UPDATECLIENT', 1);		//更新客户端缓存 开关
define('API_UPDATECREDIT', 1);		//更新用户积分 开关
define('API_GETCREDITSETTINGS', 1);	//向 UCenter 提供积分设置 开关
define('API_UPDATECREDITSETTINGS', 1);	//更新应用积分设置 开关

define('API_RETURN_SUCCEED', '1');
define('API_RETURN_FAILED', '-1');
define('API_RETURN_FORBIDDEN', '-2');
常量定义部分定义了接口所用到的 12 个接口项目的开关设置,“1”为开启“0”为关闭。如果开启,则代码段运行后返回 API_RETURN_SUCCEED,否则返回 API_RETURN_FORBIDDEN。接口运行失败则返回 API_RETURN_FAILED。

2、初始化输入参数

$code = $_GET['code'];
parse_str(authcode($code, 'DECODE', UC_KEY), $get);
if(time() - $get['time'] > 3600) {
	exit('Authracation has expiried');
}
if(empty($get)) {
	exit('Invalid Request');
}
$action = $get['action'];
$timestamp = time();
初始化输入参数负责初始化 UCenter 提交过来的接口参数,转换为接口数据供代码段处理。

2、接口代码段

接口代码根据 $get['action'] 的值执行不同的代码段,代码段的介绍如下:

test

此接口供仅测试连接。当 UCenter 发起 test 的接口请求时,如果成功获取到接口返回的 API_RETURN_SUCCEED 值,表示 UCenter 和应用通讯正常。

deleteuser

当 UCenter 删除一个用户时,会发起 deleteuser 的接口请求,通知所有应用程序删除相应的用户。
输入的参数放在 $get['ids'] 中,值为用逗号分隔的用户 ID。如果删除成功则输出 API_RETURN_SUCCEED。
deleteuser 接口示例 (PHP)

renameuser

当 UCenter 更改一个用户的用户名时,会发起 renameuser 的接口请求,通知所有应用程序改名。
输入的参数 $get['uid'] 表示用户 ID,$get['oldusername'] 表示旧用户名,$get['newusername'] 表示新用户名。如果修改成功则输出 API_RETURN_SUCCEED。
renameuser 接口示例 (PHP)

updatepw

当用户更改用户密码时,此接口负责接受 UCenter 发来的新密码。
输入的参数 $get['username'] 表示用户名,$get['password'] 表示新密码。如果修改成功则输出 API_RETURN_SUCCEED。
updatepw 接口示例 (PHP)

gettag

如果应用程序存在标签功能,可以通过此接口把应用程序的标签数据传递给 UCenter。
输入的参数放在 $get['id'] 中,值为标签名称。输出的数组需经过 uc_serialize 处理。
integer [0]标签名称
array [1] 标签数据
mixed ['xxx']自定义
自定义多个数组项,索引名任意,一同返回给 UCenter。为了保证应用间数据的共享,您需要在“应用管理管理”的“标签单条显示模板”和“标签模板标记说明”设置模板和说明。模板中“{xxx}”表示标签数据的索引,代表相应的数据。如扩展数据模板中的“{image}”将显示“['image']”数组项的内容。
gettag 接口示例 (PHP)

synlogin

如果应用程序需要和其他应用程序进行同步登录,此部分代码负责标记指定用户的登录状态。
输入的参数放在 $get['uid'] 中,值为用户 ID。此接口为通知接口,无输出内容。同步登录需使用 P3P 标准
synlogin 接口示例 (PHP)

synlogout

如果应用程序需要和其他应用程序进行同步退出登录,此部分代码负责撤销用户的登录的状态。
此接口为通知接口,无输入参数和输出内容。同步退出需使用 P3P 标准
synlogout 接口示例 (PHP)

updatebadwords

当 UCenter 的词语过滤设置变更时,此接口负责通知所有应用程序更新后的词语过滤设置内容。
设置内容用 POST 方式提交到接口。接口运行完毕输出 API_RETURN_SUCCEED。
updatebadwords 接口示例 (PHP)

updatehosts

当 UCenter 的域名解析设置变更时,此接口负责通知所有应用程序更新后的域名解析设置内容。
设置内容用 POST 方式提交到接口。接口运行完毕输出 API_RETURN_SUCCEED。
updatehosts 接口示例 (PHP)

updateapps

当 UCenter 的应用程序列表变更时,此接口负责通知所有应用程序更新后的应用程序列表。
设置内容用 POST 方式提交到接口。接口运行完毕输出 API_RETURN_SUCCEED。
updateapps 接口示例 (PHP)

updateclient

当 UCenter 的基本设置信息变更时,此接口负责通知所有应用程序更新后的基本设置内容。
设置内容用 POST 方式提交到接口。接口运行完毕输出 API_RETURN_SUCCEED。
updateclient 接口示例 (PHP)

updatecredit

当某应用执行了积分兑换请求的接口函数 uc_credit_exchange_request() 后,此接口负责通知被兑换的目的应用程序所需修改的用户积分值。
输入的参数 $get['credit'] 表示积分编号,$get['amount'] 表示积分的增减值,$get['uid'] 表示用户 ID。
updatecredit 接口示例 (PHP)

getcreditsettings

此接口负责把应用程序的积分设置传递给 UCenter,以供 UCenter 在积分兑换设置中使用。
此接口无输入参数。输出的数组需经过 uc_serialize 处理。
输出的数组单条结构:
1 维 KEY 2 维 KEY
array [n] 积分编号 string [0]积分名称
string [1]积分单位
如:
array(
        '1' => array('威望', ''),
        '2' => array('金钱', '枚'),
)
getcreditsettings 接口示例 (PHP)

updatecreditsettings

此接口负责接收 UCenter 积分兑换设置的参数。
输入的参数放在 $get['credit'] 中,值为设置的参数数组。接口运行完毕输出 API_RETURN_SUCCEED。
输入的数组单条结构:
1 维 KEY 2 维 KEY
array [appid] 应用程序 ID integer ['appiddesc']积分兑换的目标应用程序 ID
integer ['creditdesc']积分兑换的目标积分编号
integer ['creditsrc']积分兑换的源积分编号
string ['title']积分名称
string ['unit']积分单位
integer ['ratio']积分兑换比率
如:
array(
        '1' => array(
                'appiddesc' => 2,
                'creditdesc' => 1,
                'creditsrc' => 1,
                'title' => '金钱',
                'unit' => '枚',
                'ratio' => 2,
        ),
)
updatecreditsettings 接口示例 (PHP)

4、函数定义

接口函数中必须包含以下函数,否则无法正确对 UCenter 传递过来的数据进行解码。
function authcode($string, $operation = 'DECODE', $key = '', $expiry = 0) {

	$ckey_length = 4;

	$key = md5($key ? $key : UC_KEY);
	$keya = md5(substr($key, 0, 16));
	$keyb = md5(substr($key, 16, 16));
	$keyc = $ckey_length ? ($operation == 'DECODE' ? substr($string, 0, $ckey_length): substr(md5(microtime()), -$ckey_length)) : '';

	$cryptkey = $keya.md5($keya.$keyc);
	$key_length = strlen($cryptkey);

	$string = $operation == 'DECODE' ? base64_decode(substr($string, $ckey_length)) : sprintf('%010d', $expiry ? $expiry + time() : 0).substr(md5($string.$keyb), 0, 16).$string;
	$string_length = strlen($string);

	$result = '';
	$box = range(0, 255);

	$rndkey = array();
	for($i = 0; $i <= 255; $i++) {
		$rndkey[$i] = ord($cryptkey[$i % $key_length]);
	}

	for($j = $i = 0; $i < 256; $i++) {
		$j = ($j + $box[$i] + $rndkey[$i]) % 256;
		$tmp = $box[$i];
		$box[$i] = $box[$j];
		$box[$j] = $tmp;
	}

	for($a = $j = $i = 0; $i < $string_length; $i++) {
		$a = ($a + 1) % 256;
		$j = ($j + $box[$a]) % 256;
		$tmp = $box[$a];
		$box[$a] = $box[$j];
		$box[$j] = $tmp;
		$result .= chr(ord($string[$i]) ^ ($box[($box[$a] + $box[$j]) % 256]));
	}

	if($operation == 'DECODE') {
		if((substr($result, 0, 10) == 0 || substr($result, 0, 10) - time() > 0) && substr($result, 10, 16) == substr(md5(substr($result, 26).$keyb), 0, 16)) {
			return substr($result, 26);
		} else {
			return '';
		}
	} else {
		return $keyc.str_replace('=', '', base64_encode($result));
	}

}

function uc_serialize($arr, $htmlon = 0) {
	include_once UC_CLIENT_ROOT.'./lib/xml.class.php';
	return xml_serialize($arr, $htmlon);
}

function uc_unserialize($s) {
	include_once UC_CLIENT_ROOT.'./lib/xml.class.php';
	return xml_unserialize($s);
}