SDK 설정하기

AI 인게임 상점 오퍼를 사용하기 위해 필요한 SDK 설정에 대해 알아봅니다. 본 페이지는 다음과 같이 구성되어 있습니다.

  • 사전 요구사항

  • 관련 컨트롤러, 클래스, 메소드

  • 유니티 에디터에서 SDK 설정하는 법: 메시지 템플릿 생성 및 스크립트 편집

들어가기 전에

시작 전에 아래 작업들이 완료되었는지 확인합니다.

컨트롤러, 클래스, 메소드 소개

TPPersonalizedOffeController는 ShowOfferById 혹은 ShowLatestOffer메소드 호출 시, 각각의 플레이어(즉, player_uuid)에 해당하는 오퍼를 동적으로 불러와 Scene에 보여줍니다.

  • ShowOfferById와 ShowLatestOffer는 TPPersonalizedOffer 클래스의 메소드입니다.

  • TPPersonalizedOffer는 텐투플레이 개인화 오퍼와 AI 인게임 상점 출력 기능을 위한 클래스입니다.

상기 구성요소들(즉, 컨트롤러, 클래스, 메소드)은 개인화 오퍼와 AI 인게임 상점에서 공통으로 사용됩니다.

유니티 설정하기

오퍼가 제대로 보이게 하려면 유니티 에디터와 스크립트 작업이 모두 필요합니다.

  1. 유니티 에디터에서 Assets/TentuPlay/TPPersonalizedOfferTemplates에 있는 TPPersonalizedOfferController.prefab 위치를 확인합니다. TPPersonalizedOfferController.prefab은 TPPersonalizedOfferController.cs 스크립트를 컴포넌트로 갖고 있습니다.

    image (10)
    image (12)

  2. TPPersonalizedOfferController 게임 오브젝트를 Scene에 추가합니다.

    image (26)

  3. 아래의 예시 코드와 같이 tpPersonalizedOfferController GameObject 파라미터 값을 활용하여 ShowOfferById 혹은 ShowLatestOffer를 호출합니다.

    예시 코드
    public void ShowPersonalizedOffer()
    {
        TPPersonalizedOffer myTPOffer = new TPPersonalizedOffer();
        StartCoroutine(
            myTPOffer.ShowOfferById(tpPersonalizedOfferController, player_uuid, "en", offer_id, (response => { })));
    }

    자세한 예시는 Assets/ShingGoongDemo/Scripts/TentuplayRelated/TentuPlayCRMPlayerController.cs와 Assets/ShingGoongDemo/Scripts/TentuplayRelated/MailBoxOpen_offer.cs에서 확인하세요.

  4. 이제 지정된 조건에서 예시 오퍼가 게임 화면에 나타납니다.

    image (21)
    AI 인게임 상점 오퍼가 우편함에 생성된 모습
    image (22)
    AI 인게임 상점 오퍼가 화면에 노출된 모습

개인화 오퍼와 AI인게임 상점 오퍼는 OfferInfo.offerType으로 구분됩니다.

오퍼 설정하기

AI 인게임 상점 오퍼가 제대로 작동하려면 유니티 에디터에서 템플릿을 설정하고 필요시 스크립트도 수정해야 합니다.

메시지 템플릿 생성하기

ShowOfferById 혹은 ShowLatestOffer가 호출되면 Scene에 있는 TPPersonalizedOfferController(TPPersonalizedOfferController.ShowOffer)의 child로 TentuPlayAIOffer가 생성됩니다.

콘솔에서 입력한 이미지가 OfferImage의 Texture/Raw Image가 됩니다.
306
TPPersonalizedOfferController의 child로 TentuplayAIOffer가 생성된 모습

기본 템플릿으로 생성된 샘플 메시지는 아래와 같습니다.

image (25)
텐투플레이 SDK내에 포함된 기본 메시지 템플릿

이 기본 템플릿을 기반으로 원하는 템플릿을 생성할 수 있습니다.

  1. TentuPlayAIOffer의 하위 구성요소들(가령, BackgroundImage, Title 등)을 찾습니다.

    image (24)
    TentuPlayAIOffer의 child

  2. 게임에 맞게 템플릿을 편집합니다. 아래 표에는 템플릿을 구성하는 요소들과 수정 가능 여부, 그리고 그 이유에 대한 설명이 있습니다.

    구성 요소 수정 가능 수정 불가 비고

    BackgroundImage

    Rect Transform 컴포넌트의 내용

    Raw Image 컴포넌트

    콘솔에서 지정한 이미지가 Raw Image로 사용됨

    Title

    Rect Transform, Text 컴포넌트의 내용

    Text Component의 Text

    콘솔에서 지정한 본문이 Text Component의 Text를 덮어씀

    Message

    Rect Transform, Text 컴포넌트의 내용

    Text Component의 Text

    콘솔에서 설정한 본문 메시지가 Text Component의 Text를 덮어씀

    ProductImage

    Rect Transform 컴포넌트의 내용

    Image Component의 Source Image

    productInfo.sprite를 통해 동적으로 할당된 개인화 이미지가 Image Component의 Source Image를 덮어씀

    ProductButton

    Rect Transform 컴포넌트의 내용, Image

    On Click 이벤트

    버튼 클릭 시 (On Click) 이벤트는 GoToOfferEvent를 사용함

    Price

    Rect Transform, Text 컴포넌트의 내용

    Text Component의 Text

    productInfo.price를 통해 동적으로 할당된 개인화 값이 Text Component의 Text를 덮어씀

    CloseButton

    Rect Transform 컴포넌트의 내용

    On Click 이벤트

    버튼 클릭 시 (On Click) 이벤트는 CloseOfferEvent를 사용함

    Toggle

    Rect Transform 컴포넌트의 내용, Image

    On Value Changed 이벤트

    토글 체크 시 (On Value Changed) 이벤트는 CheckDoNotShowToday를 사용함

    ToggleMessage

    Rect Transform, Text 컴포넌트의 내용

    Text Component의 Text

    콘솔에서 지정한 본문이 Text Component의 Text를 덮어씀

이때 수정한 메시지 템플릿은 AI 인게임 상점에서 발송되는 모든 메시지에 대해 공통 적용됩니다.

코드 수정하기

게임 내에서 AI 인게임 상점의 메시지가 노출될 수 있도록 스크립트를 수정합니다.

스크립트 찾기

  1. TentuPlayAIOffer.prefab의 구성요소인 TentuPlayAIOffer.cs 파일을 찾습니다.

    • 파일 경로: Assets/TentuPlay/TPPersonalizedOfferTemplates/TentuPlayAIoffer.cs

      image (27)
      유니티내 TentuPlayAIOffer.cs의 위치

  2. TentuPlayAIoffer.cs 파일 내 PlaceOffer() 메소드를 수정합니다. 자세한 것은 다음 섹션에 설명되어 있습니다.

PlaceOffer 수정하기

PlaceOffer()는 AI 인게임 상점의 메시지가 화면에 노출되기 전에 실행되는 메소드입니다. 본 메소드는 텐투플레이 AI 에 의해 추천된 상품을 AI 인게임 상점의 메시지에 노출시키기 위해 먼저 추천된 상품과 관련된 정보를 가져옵니다.

먼저 product_index 또는 purchasable_slug를 이용하여 아래 항목을 가져올 수 있는 게임 내부 로직이 필요합니다.

  • sprite: AI 인게임 상점에서 추천하는 상품의 이미지

  • price: AI 인게임 상점에서 추천하는 상품의 가격 정보

  • purchase_link: AI 인게임 상점에서 추천하는 상품을 구매 또는 상품으로 이동할 수 있는 링크

  • store: 앱스토어의 별칭 (자료형: string)

  1. 플레이어의 store 스트링을 가져옵니다.

    string store = "ios";

    store 스트링은 앱스토어 이름으로 식별될 수만 있다면 어떤 값이든 상관없지만 (예: android, ios, appstore, playstore) 반드시 텐투플레이 콘솔을 통해 업로드 된 csv 파일의 'store' 컬럼의 값과 일치해야 합니다.

    • store 스트링을 사용하는 GetRecommendedProduct는 추천된 상품 중 플레이어의 마켓에 맞는 상품을 파싱해줍니다.

    • 데모 게임에서는 store의 기본값이 "ios"로 지정되어 있습니다.

  2. 텐투플레이 AI 에 의해 추천된 상품을 유저가 구매할 수 있도록 추천 상품의 purchase_link 를 가져와야 합니다.

    • 만약 텐투플레이 콘솔 > AI 인게임 상점 > 상점 운영 > 세팅 및 관리 > 정보업로드에서 업로드한 csv의 'purchase_link' 컬럼에 액션 링크를 입력했다면, 텐투플레이 SDK 가 제공하는 GetRecommendedProduct 메소드와 recommendedProduct 클래스를 이용하여 추천된 상품의 purchase_link를 아래와 같이 가져올 수 있습니다.

      purchase_link = recommendedProduct.purchase_link;

    • 만약 csv 파일의 purchase_link에 해당하는 액션 링크를 입력하지 않았다면, 아래 예시와 같이 추천 상품의 product_index 또는 purchasable_slug를 이용하여 추천된 상품의 purchase_link를 가져와야 합니다.

      purchase_link = getProductUrl(purchasable_slug); // purchase_link 를 가져오기 위한 커스텀 메소드

  3. 텐투플레이 AI 에 의해 추천된 상품의 이미지인 sprite와 가격정보인 price를 아래와 같이 product_index 또는 purchasable_slug를 이용하여 가져와야 합니다.

    ProductInfo productInfo = GetProductInfoDemo(purchasable_slug); // sprite, price(string)를 가져오기 위한 커스텀 메소드
Sprite sprite = productInfo.sprite;
string price =productInfo.price;

  4. 발송 전에 AI 인게임 상점에서 발송하는 메시지가 플레이어에게 노출되는 것이 적절한지 검증합니다.

    예를 들어 AI 인게임 상점에서 발송하는 메시지의 추천 상품이 구매 횟수 제한이 있는 상품인 경우 플레이어가 해당 상품을 구매할 수 있는지 여부를 검증해야 합니다. 플레이어가 추천 상품을 이미 구매 횟수 제한 만큼 구매하여 더 이상 구매할 수 없다면, -1을 리턴하여 해당 메시지가 플레이어에게 노출되지 않도록 합니다. 예시는 다음과 같습니다.

    대부분의 게임사는 메시지 발송 전 내부 검증 로직이 있으므로, AI 인게임 상점에서 발송되는 메시지에도 각 게임별 메시지 발송 전 이 로직을 적용할 것을 권장합니다.

    		 
    bool val = validateproduct(player_id, product_index); // 내부 검증을 위한 커스텀 메소드
if (!val)
return -1;

상기 단계에서 에러가 발생하면 -1을 리턴하여 메시지를 노출되지 않도록 하십시오.

자세한 코드는 TentuPlayAIOffer.cs를 참고하십시오.
AI 인게임 상점 메시지의 성과 데이터 올바르게 수집하기

AI 인게임 상점 메시지가 발송되면 메시지를 접한 사용자의 행동(예: Open, Dismiss, Interact)에 따라 성과 데이터 받게 됩니다. 이 성과 데이터를 통해 전송된 메시지와 메시지 수신자에 대한 중요한 정보를 얻을 수 있으며 (예: 어떤 종류의 메시지가 더 플레이어에게 더 효과적인가? 누가 적극적으로 메시지에 반응하는가?) 나아가 메시지 본문과 디자인의 개선 방안을 찾을 수 있습니다. 따라서 AI 오퍼에 대한 성과 데이터를 정확하게 수집될 수 있도록 설정하는 것이 중요합니다.

기본적으로 AI 인게임 상점 메시지 성과 데이터 수집을 위해 별도의 작업이 필요하지는 않습니다. 하지만 만약 TentuPlayAIOffer.cs 에서 관련 TPStashEvent() 코드를 수정했다거나 수정 여부를 모르겠다면 TentuPlayAIOffer.cs의 PlaceOffer() 내에서 다음과 같이 사용자의 행동에 따라 다른 메소드가 호출될 수 있도록 해야 합니다.

메시지를 열 때 호출해야 하는 메소드
TPStashEvent myStashEvent = new TPStashEvent();
myStashEvent.StashOfferEvent(
	player_uuid: player_id, offer_id: thisOffer.offer_id,
	message_status: messageStatus.Open, message_detail: purchasable_slug);

myPerOffer.OfferOpened(thisOffer.offer_id, (response) =>
        {
        });
메시지를 닫을 때 호출해야 하는 메소드 (TentuPlayAIOffer.OnCloseOfferEvent()와 동일)
int r = new TPStashEvent().StashOfferEvent(
		player_uuid: thisPlayerUUID, offer_id: thisOffer.offer_id, message_status: messageStatus.Dismiss, //Dismiss!
		message_detail: purchasable_slug);
new TPUploadData().UploadData(toCheckInterval: false);
메시지 내 버튼을 클릭하여 다음 단계로 넘어갈 때 호출해야 하는 메소드(TentuPlayAIOffer.OnGoToOfferEvent()와 동일)
int r = new TPStashEvent().StashOfferEvent(
		player_uuid: thisPlayerUUID, offer_id: thisOffer.offer_id, message_status: messageStatus.Interact, //Interact!
	  message_detail: purchasable_slug);
new TPUploadData().UploadData(toCheckInterval: false);

공통적으로 purchasable_slug가 플레이어 추천상품으로 지정되어 있는지 확인해 주세요.