# Services Core SDK API

> Initialize all Unity Gaming Services with Services Core.

Services Core 包提供了通过一次调用来初始化所有 Unity Gaming Services（Unity 游戏服务）的解决方案，并定义了供多个包使用的通用组件。这些标准化组件旨在统一 Unity Gaming Services（Unity 游戏服务）包的整体使用体验。

> **Note:**
>
> **注意**：Unity 编辑器 2019.4 及更高版本支持此 API。

## UnityServices##unityservices

```plaintext

namespace Unity.Services.Core
{
    public static class UnityServices{}
}
```

此类用于初始化项目中当前安装的所有 Unity Gaming Services（Unity 游戏服务）。

### InitializeAsync##initializeasync

```plaintext
public static Task InitializeAsync(InitializationOptions options)
```

此方法用于初始化项目中当前安装的所有 Unity Gaming Services（Unity 游戏服务）。此方法返回一个 [`Task`](https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.task?view=net-5.0)，允许查看初始化的进度。

| 参数        | 类型                                                | 描述                              |
| --------- | ------------------------------------------------- | ------------------------------- |
| `options` | [`InitializationOptions`](#initializationoptions) | 此可选参数充当键值存储，有助于实现独特的 SDK 初始化规范。 |

注意：此方法仅在运行时受支持。

### State##state

```plaintext
public static ServicesInitializationState State
```

此方法返回运行时的游戏当前 `ServicesInitializationState`：

| **值**           | **描述**                 |
| --------------- | ---------------------- |
| `Uninitialized` | Unity Services 尚未初始化。  |
| `Initializing`  | Unity Services 正在初始化中。 |
| `Initialized`   | Unity Services 已成功初始化。 |

## InitializationOptions##initializationoptions

```plaintext
namespace Unity.Services.Core 
{
    public class InitializationOptions{}
}
```

初始化选项充当键值存储，有助于实现独特的 SDK 初始化规范。初始化 Unity Gaming Services SDK 时通过 [`InitializeAsync`](#initializeasync) 方法传递这些选项。

### TryGetOption##trygetoption

```plaintext
public bool TryGetOption(string key, out bool option)
public bool TryGetOption(string key, out int option)
public bool TryGetOption(string key, out float option)
public bool TryGetOption(string key, out string option)
```

如果存在指定的键，这些方法返回 `true`，否则返回 `false`。

| 参数       | 类型   | 描述                |
| -------- | ---- | ----------------- |
| `key`    | 字符串  | 要获取的选项的键。         |
| `option` | 多种类型 | 与该键（如果存在）关联的存储选项。 |

### SetOption##setoption

```plaintext
public InitializationOptions SetOption(string key, bool value)
public InitializationOptions SetOption(string key, int value)
public InitializationOptions SetOption(string key, float value)
public InitializationOptions SetOption(string key, string value)
```

这些方法存储指定键的值。

| 参数      | 类型   | 描述                |
| ------- | ---- | ----------------- |
| `key`   | 字符串  | 要存储的选项的键。         |
| `value` | 多种类型 | 与该键（如果存在）关联的存储选项。 |

## 初始化示例##initialization-example

以下示例使用 [Environments](./service-environments.md) 初始化扩展来一次性初始化所有服务：

```plaintext
using System;
using Unity.Services.Core;
using Unity.Services.Core.Environments;
using UnityEngine;
 
public class InitializeUGS : MonoBehaviour {
    
    public string environment = "production";
 
    async void Start() {
        try {
            var options = new InitializationOptions()
                .SetEnvironmentName(environment);
 
            await UnityServices.InitializeAsync(options);
        }
        catch (Exception exception) {
            // An error occurred during initialization.
        }
    }
}
```

### 初始化调试##initialization-debugging

在 Services Core 1.4.2 及更高版本中，您可以启用详细模式以进行调试。启用详细模式后，Services Core SDK 将在编辑器控制台中记录所有服务之间共享的通用配置信息。要启用详细模式，请执行以下操作：

1. 在 Unity 编辑器中，选择 **Edit（编辑）**> **Project Settings（项目设置）**> **Player（运行设置）**。
2. 在 Player settings（运行设置）窗口中，单击 **Other Settings（其他设置）**。
3. 在 **Script Compilation（脚本编译）** 下，添加以下脚本定义符号：`ENABLE_UNITY_SERVICES_CORE_VERBOSE_LOGGING`。
4. 单击 **Apply（应用）**。


**Frame:**
![](/api/media?file=/services/media/images/enable-verbose.png)

## 异常类型##exception-types

### ServicesInitializationException##servicesinitializationexception

服务初始化期间发生的错误的基本异常类型。

### CircularDependencyException##circulardependencyexception

两个注册的 `IInitializablePackage` 实例相互依赖时发生的异常。此错误很可能凸显了设计问题，因此必须修复。

### RequestFailedException##requestfailedexception

请求失败时的基本异常类型。每个异常都会返回一个 `int ErrorCode` 来具体说明失败的原因：

| **Name**             | **代码** | 描述                                     |
| -------------------- | ------ | -------------------------------------- |
| `Unknown`            | `0`    | 无法确定错误。                                |
| `TransportError`     | `1`    | DNS、TLS 和其他传输错误，导致没有有效的 HTTP 响应。       |
| `Timeout`            | `2`    | 由于在规定时间内未收到响应，因此请求超时。                  |
| `ServiceUnavailable` | `3`    | 服务不可用。这通常意味着服务超载。                      |
| `ApiMissing`         | `4`    | 该 API 不存在。                             |
| `RequestRejected`    | `5`    | 通常在到达 API 终端之前拒绝了请求。请查看标题和详细信息以了解更多信息。 |
| `TooManyRequests`    | `50`   | 该请求有速率限制。客户端发出请求过于频繁。                  |
| `InvalidToken`       | `51`   | 身份验证令牌格式错误或无效。                         |
| `TokenExpired`       | `52`   | 身份验证令牌已到期。                             |
| `Forbidden`          | `53`   | 用户没有权限执行请求的操作。                         |
| `NotFound`           | `54`   | 找不到请求的资源。                              |
| `InvalidRequest`     | `55`   | 请求已被理解，但由于一个或多个组件无效，API 拒绝处理该请求。       |