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

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

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



## 모델

### EzPoint

광고를 시청함으로써 획득한 포인트<br>

플레이어가 광고 시청을 통해 획득한 포인트의 합계를 나타내는 모델입니다.<br>
플레이어는 광고를 시청할 때마다 포인트를 획득하며, 이 포인트는 보상 교환이나 게임 내 특전 구매 등에 사용할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| point | long |  |  | 0 | 0 ~ 9223372036854775805 | 포인트 보유 수<br>사용자가 보유하고 있는 포인트 수를 나타냅니다.<br>이 수치는 사용자가 광고를 시청함으로써 증가하고, 보상이나 특전과 교환함으로써 감소합니다. |

**관련 메서드:**
getPoint - 광고 시청으로 획득한 포인트의 현재값 조회


---

## 메서드

### getPoint

광고 시청으로 획득한 포인트의 현재값 조회<br>

리워드 광고(AdMob, Unity Ads, AppLovin MAX 등) 시청을 통해 플레이어가 획득한 포인트 수를 조회합니다.<br>
UI에 플레이어의 현재 포인트 잔액을 표시하거나, 포인트를 사용하기 전에 잔액이 충분한지 확인할 때 사용합니다.<br>
아직 포인트 레코드가 없는 경우, 0포인트의 레코드가 자동으로 생성되어 반환됩니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzPoint](#ezpoint) | 광고 시청으로 획득한 포인트|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.AdReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Point(
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.AdReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Point(
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->AdReward->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Point(
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

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

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

var result = async_result.result

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.AdReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Point(
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.AdReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Point(
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->AdReward->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Point(
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::AdReward::Model::FPoint> value) {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->Unsubscribe(CallbackId);

```

**Godot**
```gdscript

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

# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
    # 값이 변화했을 때 호출됨
    # value에는 변경 후의 값이 전달됩니다
    pass
)

# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---

## 이벤트 핸들러

### OnChangePointNotification

광고 시청으로 포인트가 변동되었을 때의 푸시 알림

 | 이름 | 타입 | 설명 |
| --- | --- | --- |
| namespaceName | string |네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.|
| userId | string |사용자ID|

#### 구현 예제





**Unity (UniTask)**
```csharp

    gs2.AdReward.OnChangePointNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
    };
```

**Unity (Vanilla)**
```cs

    gs2.AdReward.OnChangePointNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
    };
```

**Unreal Engine 5**
```cpp

    Gs2->AdReward->OnChangePointNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto UserId = Notification->UserIdValue;
    });
```

**Godot**
```gdscript

    ez.ad_reward.change_point_notification.connect(func(notification):
        var namespace_name = notification.namespace_name
        var user_id = notification.user_id
    )
```


---