> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-News SDK for Game Engine API 레퍼런스

게임 엔진용 GS2-News SDK의 모델 사양과 API 레퍼런스



## 모델

### EzNews

공지사항 게시글<br>

Hugo 사이트 데이터로부터 생성된 개별 뉴스 게시글을 나타냅니다.<br>
각 게시글은 섹션과 콘텐츠 경로에 속하며, 제목, 타임스탬프, Front Matter 메타데이터를 가집니다.<br>
게시글은 필요에 따라 GS2-Schedule의 이벤트와 연결하여 표시 기간을 제어할 수 있습니다.<br>
Front Matter에는 JSON 형식의 추가 메타데이터가 포함되며, 표시 순서를 제어하기 위한 선택적 weight 필드도 포함됩니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| section | string |  | ✓ |  |  ~ 1024자 | 섹션 이름<br>이 게시글이 속한 섹션(카테고리)이며, Hugo의 콘텐츠 디렉터리 구조에 대응합니다.<br>게시글을 표시용 논리 그룹으로 구성하는 데 사용됩니다. |
| content | string |  | ✓ |  |  ~ 1024자 | 콘텐츠<br>섹션 내에서 이 게시글의 콘텐츠 경로 식별자입니다.<br>섹션과 함께 Hugo 콘텐츠 구조 내에서 게시글의 위치를 고유하게 식별합니다. |
| title | string |  | ✓ |  |  ~ 1024자 | 게시글 제목<br>뉴스 게시글의 제목이며, 일반적으로 Hugo의 Front Matter에서 정의됩니다.<br>플레이어에게 게시글 목록을 표시할 때 제목으로 표시됩니다. |
| scheduleEventId | string |  |  |  |  ~ 1024자 | GS2-Schedule 이벤트 GRN |
| timestamp | long |  | ✓ |  |  | 타임스탬프<br>UNIX 시간(밀리초) |
| frontMatter | string |  | ✓ |  |  ~ 1024자 | Front Matter<br>게시글에 연결된 JSON 형식의 메타데이터이며, 원래 Hugo 마크다운의 Front Matter에서 정의됩니다.<br>weight(표시 순서 제어용), 태그, 카테고리 등 임의의 사용자 정의 속성 필드를 포함할 수 있습니다. |

**관련 메서드:**
listNewses - 공지사항 게시글 목록 조회


---

### EzSetCookieRequestEntry

Cookie 설정 요청 엔트리<br>

뉴스 게시글의 웹 콘텐츠에 접근하기 위해 브라우저/WebView에 설정해야 하는 Cookie의 키-값 쌍을 나타냅니다.<br>
클라이언트는 게시글 URL을 불러오기 전에 이 Cookie를 설정하여 콘텐츠에 대한 인가된 접근을 보장해야 합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| key | string |  | ✓ |  |  ~ 128자 | Cookie 키<br>뉴스 콘텐츠에 인증된 방식으로 접근하기 위해 설정해야 하는 Cookie의 이름입니다.<br>최대 128자. |
| value | string |  | ✓ |  |  ~ 1024자 | Cookie 값<br>뉴스 콘텐츠에 인증된 방식으로 접근하기 위해 설정해야 하는 Cookie의 값입니다.<br>최대 1024자. |

**관련 메서드:**
getContentsUrl - 공지사항 콘텐츠를 표시하기 위한 URL과 쿠키 조회


---

## 메서드

### getContentsUrl

공지사항 콘텐츠를 표시하기 위한 URL과 쿠키 조회<br>

WebView나 브라우저에서 공지사항 게시글을 표시하는 데 필요한 정보를 조회합니다.<br>
공지사항 콘텐츠는 웹 페이지 형태로 호스팅되므로, 이를 표시하려면 (1) 인증용 쿠키와 (2) 열어야 할 URL이 필요합니다.<br>
응답에는 브라우저 URL(쿠키 설정이 먼저 필요)과 ZIP URL(쿠키 없이 모든 콘텐츠를 다운로드 가능 — 오프라인 이용이나 커스텀 렌더링에 유용)이 포함됩니다.<br>
공지사항 게시글을 열기 전에 사용합니다. 예를 들어 이 API를 호출하여 반환된 쿠키를 WebView에 설정한 후, 브라우저 URL로 이동하여 게시글을 표시합니다. 또는 ZIP을 다운로드하여 게임 UI에서 네이티브로 콘텐츠를 렌더링할 수도 있습니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzSetCookieRequestEntry&gt;](#ezsetcookierequestentry) | 공지 웹 콘텐츠에 액세스하기 위해 설정이 필요한 쿠키 리스트|
| browserUrl | string | 공지 웹 콘텐츠에 액세스하기 위한 URL|
| zipUrl | string | ZIP 형식의 공지 웹 콘텐츠에 액세스하기 위한 URL (액세스에 Cookie 설정 불필요)|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.News.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).News(
    );
    var result = await domain.GetContentsUrlAsync(
    );
    List<EzSetCookieRequestEntry> cookies = new List<EzSetCookieRequestEntry>();
	var items = result.ToList();
	foreach (var item in items)
	{
	  var entry = await item.ModelAsync();
	  cookies.Add(entry);
	}
    var browserUrl = domain.BrowserUrl;
    var zipUrl = domain.ZipUrl;

```

**Unity (Vanilla)**
```cs
    var domain = gs2.News.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).News(
    );
    var future = domain.GetContentsUrlFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    List<EzSetCookieRequestEntry> cookies = new List<EzSetCookieRequestEntry>();
    var result = future.Result;
    var items = result.ToList();
    foreach (var item in items)
    {
        var future2 = item.Model();
	    yield return future2;
	    var entry = future2.Result;
	    cookies.Add(entry);
    }
    var browserUrl = domain.BrowserUrl;
    var zipUrl = domain.ZipUrl;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->News->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->News(
    );
    const auto Future = Domain->GetContentsUrl(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    TArray<EzSetCookieRequestEntryPtr> Cookies;
	const auto It = Future->GetTask().Result();
	foreach (auto Item in It)
	{
        const auto Future2 = Item.Model();
        Future2->StartSynchronousTask();
        if (Future2->GetTask().IsError())
        {
            return Future2->GetTask().Error();
        }
        Cookies.Add(Future2->GetTask().Result());
	}
    const auto BrowserUrl = Domain->BrowserUrl;
    const auto ZipUrl = Domain->ZipUrl;

```

**Godot**
```gdscript

var domain = ez.news.namespace_(
        "namespace-0001"
    ).me(game_session).news(
    )

var async_result = await domain.get_contents_url(
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---

### listNewses

공지사항 게시글 목록 조회<br>

플레이어를 위한 게임 내 공지사항 게시글(공지)의 목록을 조회합니다.<br>
공지사항 게시글은 GS2에서 관리되는 HTML 기반 웹 콘텐츠입니다. 예를 들어 점검 공지, 이벤트 공지, 업데이트 패치 노트, 캠페인 정보 등이 있습니다.<br>
응답에는 캐시 검증용 해시 값도 포함되어 있어, 이전 조회 시점 이후 콘텐츠가 변경되었는지 확인할 수 있습니다.<br>
게임 내 공지사항 화면을 구성하는 데 사용합니다. 예를 들어 "3월 1일 점검 안내", "신규 이벤트: 봄맞이 축제", "버전 2.5 업데이트 노트"와 같은 게시글 목록을 표시할 때 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzNews&gt;](#eznews) | 공지 기사 리스트|
| contentHash | string | 공지 기사 데이터의 해시 값|
| templateHash | string | 템플릿 데이터의 해시 값|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.News.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.NewsesAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.News.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Newses(
    );
    List<EzNews> items = new List<EzNews>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->News->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Newses(
    );
    TArray<Gs2::UE5::News::Model::FEzNewsPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


---