README

TrackBase 为其用户和希望以自己的方式展示 TrackBase 数据的部落提供了自己的 API。在 开发者平台 上注册的用户可以查询我们提供的多个 API，无论是使用他们喜欢的任何编程语言，还是通过标准 cURL 请求。通过这个包，TrackBase 希望提供一个更简单的途径来从其服务器收集信息，无需了解如何编码。对 API 的标准请求只需要 两行代码。

请确保您首先在 开发者注册 并阅读我们的 API 文档，以更好地了解我们如何返回信息以及您需要提供哪些参数。此外，最重要的是，请查看以下文档中的 如何使用 部分。

安装

Composer

推荐使用 Composer 安装和使用我们的库。

在您的终端中执行以下代码行，将我们的库安装到项目中

composer require trackbasenet/dev-api

或者您也可以通过以下方式将我们的库添加到您的项目中的 composer.json 文件中

{
	"require": {
		"trackbasenet/dev-api": "*"
	}
}

最终，您需要在终端中执行以下行来安装我们的库

composer install

ZIP 下载

如果您不熟悉或不想使用 Composer，也可以下载最新的 ZIP 压缩包 并包含 src/autoload.php 文件。这绕过了版本系统并下载到最新的提交。

最终，您需要像这样 require_once 自动加载器

require_once __DIR__ . '/src/autoload.php';

如何使用

实例化

在运行任何方法之前，您需要实例化 TrackBaseApi 类并提供查询我们 API 所需的必要凭据。

<?php

$options = [
	'game' => 'et'
];

$api = new \TrackBaseNet\TrackBaseApi($app_id, $relation_token, $_aak, $options);

由于 $options 当前仅支持设置一个游戏，您需要对该游戏进行查询请求。目前，只有 et 可用。这意味着，您不需要提供 $options 数组。

可用方法

在实例化您的 TrackBaseApi 类后，您可以直接在对象上运行任何支持的方法。以下方法受支持

• ranklist（排名 API）
• toplist（排名 API）
• clanRanklist（排名 API）
• clanToplist（排名 API）
• playerInfo（玩家 API）
• playerServers（玩家 API）
• playerSessions（玩家 API）
• clanInfo（部落 API）
• serverInfo（服务器 API）
• serverSessions（服务器 API）
• serverUsage（服务器 API）
• userInfo（用户 API）
• getUser（用户 API）
• connectUser（用户 API）
• collectNewUser（用户 API）

ranklist

/*
 * Available options, specifically for this method:
 * order: 'asc' or 'desc'
 * limit: any integer between 1 and 50
 * start: any integer greater than 0, useful for pagination
 */

// Following options are default and do not need to be supplied by default
$options = [
	'order' => 'asc',
	'limit' => 10,
	'start' => 1
];

$api->ranklist($options);

toplist

/*
 * Available options, specifically for this method:
 * order: 'asc' or 'desc'
 * limit: any integer between 1 and 50
 * start: any integer greater than 0, useful for pagination
 */

// Following options are default and do not need to be supplied by default
$options = [
	'order' => 'asc',
	'limit' => 10,
	'start' => 1
];

$api->toplist($options);

clanRanklist

/*
 * Available options, specifically for this method:
 * order: 'asc' or 'desc'
 * limit: any integer between 1 and 50
 * start: any integer greater than 0, useful for pagination
 */

// Following options are default and do not need to be supplied by default
$options = [
	'order' => 'asc',
	'limit' => 10,
	'start' => 1
];

$api->clanRanklist($options);

clanToplist

/*
 * Available options, specifically for this method:
 * order: 'asc' or 'desc'
 * limit: any integer between 1 and 50
 * start: any integer greater than 0, useful for pagination
 */

// Following options are default and do not need to be supplied by default
$options = [
	'order' => 'asc',
	'limit' => 10,
	'start' => 1
];

$api->clanToplist($options);

playerInfo

/*
 * Available options, specifically for this method:
 * pid: any integer greater than 0 that corresponds to a player's ID
 * order: 'asc' or 'desc'
 * limit: any integer between 1 and 50
 * start: any integer greater than 0, useful for pagination
 */

// Following options are default and do not need to be supplied by default
$options = [
	'pid' => 1,
	'order' => 'asc',
	'limit' => 10,
	'start' => 1
];

$api->playerInfo($options);

playerServers

/*
 * Available options, specifically for this method:
 * pid: any integer greater than 0 that corresponds to a player's ID
 * order: 'asc' or 'desc'
 * limit: any integer between 1 and 50
 * start: any integer greater than 0, useful for pagination
 */

// Following options are default and do not need to be supplied by default
$options = [
	'pid' => 1,
	'order' => 'asc',
	'limit' => 10,
	'start' => 1
];

$api->playerServers($options);

playerSessions

/*
 * Available options, specifically for this method:
 * pid: any integer greater than 0 that corresponds to a player's ID
 * order: 'asc' or 'desc'
 * limit: any integer between 1 and 50
 * start: any integer greater than 0, useful for pagination
 */

// Following options are default and do not need to be supplied by default
$options = [
	'pid' => 1,
	'order' => 'asc',
	'limit' => 10,
	'start' => 1
];

$api->playerSessions($options);

clanInfo

/*
 * Available options, specifically for this method:
 * cid: any integer greater than 0 that corresponds to a clan's ID
 * order: 'asc' or 'desc'
 */

// Following options are default and do not need to be supplied by default
$options = [
	'cid' => 1,
	'order' => 'asc',
];

$api->clanInfo($options);

serverInfo

/*
 * Available options, specifically for this method:
 * sid: any integer greater than 0 that corresponds to a server's ID
 * order-by: one of the following: ['xp', 'rate', 'rating', 'ping', 'class', 'kills', 'deaths', 'playername']
 * order: 'asc' or 'desc'
 * limit: any integer between 1 and 50
 * start: any integer greater than 0, useful for pagination
 */

// Following options are default and do not need to be supplied by default
$options = [
	'sid' => 1,
	'order-by' => 'rate',
	'order' => 'desc',
	'limit' => 10,
	'start' => 1
];

$api->serverInfo($options);

serverSessions

/*
 * Available options, specifically for this method:
 * sid: any integer greater than 0 that corresponds to a server's ID
 * order-by: 'time'
 * order: 'asc' or 'desc'
 * limit: any integer between 1 and 50
 * start: any integer greater than 0, useful for pagination
 */

// Following options are default and do not need to be supplied by default
$options = [
	'sid' => 1,
	'order-by' => 'time',
	'order' => 'desc',
	'limit' => 10,
	'start' => 1
];

$api->serverSessions($options);

serverUsage

/*
 * Available options, specifically for this method:
 * sid: any integer greater than 0 that corresponds to a server's ID
 * order-by: one of the following: ['playername', 'rate', 'rating', 'time', 'ratetime', 'lastseen']
 * order: 'asc' or 'desc'
 * limit: any integer between 1 and 50
 * start: any integer greater than 0, useful for pagination
 */

// Following options are default and do not need to be supplied by default
$options = [
	'sid' => 1,
	'order-by' => 'rate',
	'order' => 'desc',
	'limit' => 10,
	'start' => 1
];

$api->serverUsage($options);

userInfo

/*
 * Available options, specifically for this method:
 * uid: any integer greater than 0 that corresponds to a user's ID
 * request: binary request number that translates to the information that should be received. For more information, please check the documentation / your app on our developers platform
 */

// Following options are default and do not need to be supplied by default
$options = [
	'uid' => 0,
	'request' => 0
];

$api->userInfo($options);

getUser

// This method is a shortcut for the ->userInfo() method and receives the $user_id and $request integers as its arguments
$api->getUser($user_id, $request);

connectUser

// This method can be called when you want to connect a user to your app. It returns a redirection header to our developers platform.
$api->connectUser();

collectNewUser

// This method needs to be called on the URI that has been submitted as your "Server URL" in your app settings. It holds the logic for fetching a user in the correct way. It requires your apps $returnToken as well as a return method that will be called once your site registers a new call from TrackBase with a new user ID. The $user_id will be its only parameter.
$possible_new_user_id = $api->collectNewUser($returnToken, function ($user_id) {
// Any logic to store the user ID
// This can either be a database call inside this method,
// or return the user ID itself. If so, you might want to catch this methods return inside a new variable ($possible_new_user_id)
});

全局方法

一些方法是全局的，可以在任何 API 方法上调用。

• countResults
• firstResult
• getResults
• getStatusCode
• getMessage
• getError
• getErrorCode
• hasErrors

countResults

此方法返回返回的行数。在某些情况下，这可能与预期数字不符。有关详细信息，请参阅API文档。

$topTenPlayers_count = $api->ranklist()->countResults();

firstResult

此方法返回结果集的第一个结果。如果没有结果，或查询返回了错误，将返回NULL。

$topPlayer = $api->ranklist()->firstResult();

getResults

此方法返回整个结果集。如果没有结果，或查询返回了错误，将返回一个空的[]数组。

$topTenPlayers = $api->ranklist()->getResults();

getStatusCode

此方法返回任何查询返回的状态码。200表示查询良好。

$requestStatusCode = $api->ranklist()->getStatusCode();

getMessage

此方法返回任何查询返回的消息。如果有错误返回，将为空。

$requestMessage = $api->ranklist()->getMessage();

getError

此方法返回任何查询返回的错误消息。如果没有错误返回，将为空。

$requestErrorMessage = $api->ranklist()->getError();

getErrorCode

此方法返回错误代码。这对于调试目的或在联系我们时遇到问题时非常有用。有关详细信息，请参阅getError方法。

$requestErrorCode = $api->ranklist()->getErrorCode();

hasErrors

此方法返回是否返回了错误。可以用来轻松查看查询是否成功。要进行进一步检查，您可能需要使用countResults方法。

$hasErrors = $api->ranklist()->hasErrors();

if ($hasErrors) {
	// Show errors
}

示例

接收TSP排名列表的前10名玩家

$api = new \TrackBaseNet\TrackBaseApi($app_id, $relation_token, $_aak, ['game' => 'et']);

$results = $api->ranklist(['order' => 'asc', 'limit' => 10, 'start' => 1])->getResults();

或者更快

$api = new \TrackBaseNet\TrackBaseApi($app_id, $relation_token, $_aak);

$results = $api->ranklist()->getResults();

接收服务器上最后5次游玩的会话

$api = new \TrackBaseNet\TrackBaseApi($app_id, $relation_token, $_aak);

$results = $api->serverSessions(['sid' => 1234, 'limit' => 5])->getResults();

以HTML格式接收并显示特定的玩家名称

$api = new \TrackBaseNet\TrackBaseApi($app_id, $relation_token, $_aak);

$player = $api->playerInfo(['pid' => 1234])->firstResult();

echo "Hello, {$player->playername_html}!";

监听TrackBase返回带有新用户信息的调用

$api = new \TrackBaseNet\TrackBaseApi($app_id, $relation_token, $_aak);

$api->collectNewUser($returnToken, function ($user_id) use ($database) {
	$database->insertRow('users_table', ['trackbase_userid' => $user_id]);
});

获取用户信息

$api = new \TrackBaseNet\TrackBaseApi($app_id, $relation_token, $_aak);

// Get the user's username
$api->userInfo([
	'uid' => $user_id,
	'request' => 1
]);

或者更快

$api = new \TrackBaseNet\TrackBaseApi($app_id, $relation_token, $_aak);

// Get the user's username
$api->getUser($user_id, 1);

支持

如果您对此库有任何问题或发现任何问题，请创建一个问题，访问我们的论坛，加入我们的Discord服务器或给我们发邮件。感谢您的帮助！

捐赠

如果您重视我们的工作并想帮助我们支付服务器费用，请考虑捐赠。您将收到我们的一份精美礼物！