# GameKit Share DTO

本文档只定义 Unity GameKit Share 暴露给游戏侧使用的数据结构。desktop 负责决定登录、确认面板、上传、发布、取消、失败处理和其他分享流程细节；这些流程不属于 DTO 定义。

DTO 中不包含构造函数、编码函数或发布逻辑。图片内容使用 `byte[]`，不是文件路径、URL 或 base64 字符串。

## IGPShareRequest

`IGPShareRequest` 是游戏发起一次分享时提交的请求 DTO。

```csharp
public sealed class IGPShareRequest
{
    public int schemaVersion = 1;
    public string? contentType;
    public string? title;
    public string? text;
    public IGPShareImage[] images = Array.Empty<IGPShareImage>();
    public string? templateId;
    public object? data;
    public object? metadata;
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `schemaVersion` | `int` | 是 | 请求 DTO 版本，当前为 `1`。 |
| `contentType` | `string?` | 否 | 游戏自定义内容类型，例如 `score-card`、`level-share`、`character-card`、`replay`。 |
| `title` | `string?` | 否 | 分享标题。 |
| `text` | `string?` | 否 | 分享正文文本。 |
| `images` | `IGPShareImage[]` | 否 | 分享图片列表，支持多张图片；每张图片的内容放在 `IGPShareImage.bytes`。 |
| `templateId` | `string?` | 否 | 模板 ID，由游戏和 desktop 约定具体含义。 |
| `data` | `object?` | 否 | 游戏自定义业务数据，例如分数、关卡、角色、战绩、回放 ID。SDK 不解释该字段。 |
| `metadata` | `object?` | 否 | 游戏自定义元数据，例如 `matchId`、`levelId`、`traceId`、`source`。SDK 不解释该字段。 |

## IGPShareImage

`IGPShareImage` 是单张分享图片的 DTO。

```csharp
public sealed class IGPShareImage
{
    public string mimeType = string.Empty;
    public byte[] bytes = Array.Empty<byte>();
    public int? width;
    public int? height;
    public string? fileName;
    public string? altText;
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `mimeType` | `string` | 是 | 图片 MIME 类型，例如 `image/png` 或 `image/jpeg`。 |
| `bytes` | `byte[]` | 是 | 图片原始字节内容；不是路径、URL、JSON 字段或 base64 字符串。 |
| `width` | `int?` | 否 | 图片宽度，单位为像素。 |
| `height` | `int?` | 否 | 图片高度，单位为像素。 |
| `fileName` | `string?` | 否 | 可选文件名，例如 `score.png`，用于展示、上传或日志等 desktop 自主决定的场景。 |
| `altText` | `string?` | 否 | 可选替代文本，用于无障碍、审核、预览说明等场景。 |

## IGPShareResult

`IGPShareResult` 是 desktop 完成分享流程后返回给游戏侧的结果 DTO。

```csharp
public sealed class IGPShareResult
{
    public bool success = true;
    public string code = string.Empty;
    public string shareId = string.Empty;
    public string status = string.Empty;
    public string message = string.Empty;
    public object? data;
    public string contentJson = string.Empty;
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `success` | `bool` | 是 | 分享流程是否成功完成。用户取消、登录未完成或发布失败时可为 `false`。 |
| `code` | `string` | 否 | desktop 返回的结果码，例如 `SHARE_COMPLETED`、`SHARE_CANCELLED`、`SHARE_LOGIN_REQUIRED`、`SHARE_DESKTOP_ERROR`。 |
| `shareId` | `string` | 否 | desktop 或分享目标平台生成的分享 ID；没有时为空字符串。 |
| `status` | `string` | 否 | desktop 返回的状态，例如 `completed`、`cancelled`、`loginRequired`、`failed`。 |
| `message` | `string` | 否 | desktop 返回的说明文本，可用于日志、调试或必要的用户提示。 |
| `data` | `object?` | 否 | desktop 返回的扩展结果数据；具体结构由 desktop 决定。 |
| `contentJson` | `string` | 否 | desktop 返回的原始结果 JSON 字符串；主要用于兼容、调试或排查问题。 |

## 示例

```csharp
var request = new IGPShareRequest
{
    schemaVersion = 1,
    contentType = "score-card",
    title = "New record",
    text = "I scored 12345",
    templateId = "score",
    images = new[]
    {
        new IGPShareImage
        {
            mimeType = "image/png",
            bytes = posterPngBytes,
            width = 1280,
            height = 720,
            fileName = "score.png",
            altText = "score card",
        },
    },
    data = new
    {
        score = 12345,
        level = "hard",
    },
    metadata = new
    {
        matchId = "match-1",
        traceId = "trace-1",
    },
};

IGPShareResult result = await IGPShare.ShareAsync(runtimeManager, request);
```
