콘텐츠로 이동

사용 예시

'우편함'을 사용하는 예시입니다. 실제 서비스 환경에서는 앱 운영 정책과 앱 UI/UX에 맞게 구현해야 합니다.

모든 우편함 메서드를 호출하려면 로그인한 사용자의 활성 세션이 필요합니다. 먼저 모듈 설치, 초기화, 로그인을 완료하세요.

  • 보상 우편 발송 및 상태 확인
  • 수신 우편 확인 및 우편 상태 변경
  • 수신 우편 삭제
  • 잘못 발송한 우편 회수 및 발신 우편 정리

보상 우편 발송 및 상태 확인

랭킹 보상이나 출석 보상처럼 특정 조건을 만족한 사용자에게 우편을 발송하고, 발송 뒤 상태를 확인합니다.

  1. 앱 서버 또는 앱 클라이언트에서 보상 지급 조건을 확인하고 우편 제목, 본문, 발신자 이름, 만료 시각, 수신 대상, 첨부 아이템을 준비합니다.

  2. 우편을 발송합니다. RecipientScope를 Direct로 지정하고 RecipientPlayerIds에 수신자 PlayerId 목록을 담으며, 첨부 아이템이 있는 우편이면 Attachments에 첨부 아이템 목록을 넣습니다.

  3. 우편 발송 결과를 처리합니다. 발송에 성공하면 응답 데이터의 MailId를 저장합니다. 이후 발송 상태 확인, 회수, 발송 이력 정리에 MailId를 사용합니다. 성공 응답을 받지 못하면 우편 발송의 응답 상태에 따라 처리합니다.

  4. 발신 우편 정보 조회를 합니다. 발송 직후 특정 우편 상태를 바로 확인하려면 저장한 MailId로 GetMailAsync()를 호출하고, 발송 이력을 함께 보거나 MailId를 다시 찾아야 하면 GetSentMailsAsync()를 사용해 MailStatus, ExpiresAt, 수신 대상 수를 확인합니다.

수신 우편 확인 및 우편 상태 변경

사용자가 우편함 화면에서 첨부 아이템이 담긴 우편을 확인하고 우편을 열었을 때, 본문 읽음 상태와 첨부 아이템 수령 상태를 분리해 반영합니다.

  1. 사용자가 앱 내 우편함 화면에 진입합니다.

  2. 수신 우편 목록을 조회합니다. 우편함 목록 화면을 구현할 때는 앱 클라이언트에서 GetReceivedMailsAsync()를 호출해 수신 우편 목록을 불러옵니다. 우편 목록 화면에는 제목, 만료 시각, 읽음 여부를 요약해 표시합니다.

  3. 사용자가 우편 목록 화면에서 특정 우편을 선택하면 GetReceivedMailAsync()를 호출해 우편 본문, 첨부 아이템, MailStatus, TextReadAt, AttachmentReadAt을 함께 확인합니다. 이때 Language를 함께 전달합니다.

  4. 사용자가 선택한 우편 본문을 읽은 시점에 MarkMailAsReadAsync()를 Target = Text로 호출해 본문 읽음 상태를 반영합니다.

  5. 사용자가 첨부 아이템을 확인하거나 앱이 다운로드 완료를 판단하면 앱 클라이언트 또는 앱 서버에서 실제 첨부 아이템을 처리합니다. 그 판단이 끝난 시점에 앱 클라이언트가 MarkMailAsReadAsync()를 Target = Attachment 또는 All로 호출해 첨부 아이템 수령 상태를 반영합니다.

  6. 읽음 결과를 처리합니다. 성공 응답을 받으면 응답의 TextReadAt, AttachmentReadAt을 기준으로 우편함 화면 상태를 즉시 갱신합니다. 성공 응답을 받지 못하면 읽음 처리의 응답 상태에 따라 처리합니다.

수신 우편 삭제

사용자가 이미 확인한 우편이나 더 이상 보관하지 않을 우편을 우편함 목록에서 정리합니다.

  1. 사용자가 우편함 목록 화면에서 삭제할 우편을 선택합니다.

  2. 앱 클라이언트는 삭제 대상 우편의 MailRecipientId를 확인합니다. 첨부 아이템 수령 완료 여부나 만료 여부를 함께 보여 주고 싶다면 필요에 따라 GetReceivedMailAsync() 결과를 확인합니다.

  3. 수신 우편을 삭제합니다.

  4. 삭제 결과를 처리합니다. 성공 응답을 받으면 삭제된 우편을 우편함 목록에서 제거하고 남은 우편 수를 다시 계산합니다. 성공 응답을 받지 못하면 수신 우편 삭제의 응답 상태에 따라 처리합니다.

잘못 발송한 우편 회수 및 발신 우편 정리

잘못 보낸 우편이나 더 이상 노출되면 안 되는 우편을 회수하고, 필요하면 발신 우편 이력에서도 정리합니다.

  1. 앱 서버 또는 클라이언트가 회수할 발신 우편의 MailId를 확인합니다. 발송 직후 저장한 값을 그대로 쓸 수 있고, 필요하면 발신 우편 정보 조회에서 GetMailAsync() 또는 GetSentMailsAsync()로 다시 찾습니다.

  2. 우편을 회수합니다.

  3. 우편 회수 결과를 처리합니다. 성공 응답을 받으면 발신 우편 상태는 즉시 Revoked로 바뀌며 수신 우편 회수는 비동기로 진행됩니다. 성공 응답을 받지 못하면 우편 회수의 응답 상태에 따라 처리합니다.

  4. 같은 MailId로 우편 정보를 다시 조회합니다. 최신 상태를 다시 보여 줘야 하면 GetMailAsync()를 다시 호출해 MailStatus가 Revoked인지 확인하고, 우편함 UI 상태를 갱신합니다. 삭제 전에 만료 여부도 함께 보여 주려면 이 단계에서 ExpiresAt도 같이 확인합니다.

  5. 회수된 발신 우편을 우편함 UI의 발신 우편 목록에서 즉시 감추려면 발신 우편을 삭제합니다. 발송 직후 저장한 MailId를 그대로 사용하거나, 바로 앞 단계에서 다시 확인한 MailId를 사용합니다.

  6. 삭제 결과를 처리합니다. 성공 응답을 받으면 삭제된 발신 우편을 목록과 상세 화면에서 제거합니다. 성공 응답을 받지 못하면 발신 우편 삭제의 응답 상태에 따라 처리합니다.

더 알아보기