Blocklist

1. 概述

黑名单服务允许开发者管理玩家黑名单。当玩家被加入或移出黑名单时，不会向其推送任何通知。

每个玩家都可以将其他玩家添加到黑名单中，用于限制他们之间的互动行为，如聊天、好友请求、组队等。

完成本教程后，开发者将了解：

如何管理游戏内黑名单
如何同步账号平台的黑名单

您可以在网页控制台中查询黑名单，如下所示。

blocklist

2. 功能特性

2.1 游戏内黑名单

由游戏自身维护的黑名单。

管理黑名单
查询： 获取玩家的黑名单。
添加： 玩家可以将其他玩家添加到黑名单中。被添加的玩家不会收到通知。
移除： 从玩家的黑名单中移除玩家。

2.2 账号平台黑名单

由各平台（如Xbox、PS5、Steam等）维护的黑名单。为了使平台黑名单在游戏中生效，开发者需要将平台的黑名单同步到PGOS。同步需要及时，建议在玩家成功登录PGOS后立即同步平台黑名单到PGOS。当然，当检测到平台黑名单发生变化时，游戏也需要尽快同步最新的黑名单。

❗ 注意
开发者通常不需要关注平台黑名单的内容。仅当游戏需要在主机平台发布时，才会根据主机平台的合规要求使用相关接口。

同步账号平台黑名单： 将平台黑名单完整同步至PGOS。
同步新增账号平台黑名单： 在完整同步后，任何新增的数据也需同步至PGOS。
同步移除账号平台黑名单： 在完整同步后，任何被移除的数据也需同步至PGOS。
同步账号平台语音黑名单： 将平台语音黑名单完整同步至PGOS。

3. 使用黑名单服务(游戏内)

3.1 获取黑名单

首先获取玩家的黑名单。

按照以下方式调用黑名单模块中的GetBlocklist:

UE C++
UE BP

#include "PgosSDKCpp.h"
#include "Core/PgosErrorCode.h"

void SomeUObjectClass::GetBlocklist()
{
    auto blocklist = IPgosSDKCpp::Get().GetClientBlocklistAPI();
    if (blocklist)
    {
        blocklist->GetBlocklist([](const FPgosResult& Ret, const FClientBlocklistInfo* Data) {
            if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
            {
                UE_LOG(LogTemp, Log, TEXT("OnGetBlocklistSuccess"));
            }
            else
            {
                UE_LOG(LogTemp, Log, TEXT("OnGetBlocklistFailed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
            }
        });
    }
}

#include "PgosClientBlocklistAPI.h"

void SomeUObjectClass::GetBlocklist()
{
    PGOS_CALL_ASYNC_API(UPgosClientAPIGetBlocklist::GetBlocklist,
                        this,
                        &SomeUObjectClass::OnGetBlocklistSuccess,
                        &SomeUObjectClass::OnGetBlocklistFailed);
}

void SomeUObjectClass::OnGetBlocklistSuccess(
    FPgosResult Error, FClientBlocklistInfo ListInfo)
{
      UE_LOG(LogTemp, Log, TEXT("OnGetBlocklistSuccess"));
}

void SomeUObjectClass::OnGetBlocklistFailed(
    FPgosResult Error, FClientBlocklistInfo ListInfo)
{
      UE_LOG(LogTemp, Error, TEXT("OnGetBlocklistFailed: err_code=%d, err_msg=%s"), Result.err_code, *Result.msg);
}

如果成功，将返回玩家的黑名单。

如果结果为"fail"，请检查错误代码和错误信息以了解发生了什么。

❗ 注意
如果游戏同步了账号平台的黑名单，返回结果将同时包含游戏内黑名单和账号平台黑名单。

3.2 添加至黑名单

当您想要将其他玩家添加到玩家的黑名单时，您需要获取目标玩家的玩家ID，并调用AddToBlocklist函数。

从Blocklist模块调用AddToBlocklist，具体如下：

UE C++
UE BP

#include "PgosSDKCpp.h"
#include "Core/PgosErrorCode.h"

void SomeUObjectClass::AddToBlocklist()
{
    FString PlayerId = ObtainFromSomeWhere(); // The id for target player.
    auto blocklist = IPgosSDKCpp::Get().GetClientBlocklistAPI();
    if (blocklist)
    {
        blocklist->AddToBlocklist(PlayerId, [](const FPgosResult& Ret) {
            if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
            {
                UE_LOG(LogTemp, Log, TEXT("OnAddToBlocklistSuccess"));
            }
            else
            {
                UE_LOG(LogTemp, Log, TEXT("OnAddToBlocklistFailed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
            }
        });
    }
}

#include "PgosClientBlocklistAPI.h"

void SomeUObjectClass::AddToBlocklist()
{
    FString PlayerId = ObtainFromSomeWhere(); // The id for target player.
    PGOS_CALL_ASYNC_API(UPgosClientAPIAddToBlocklist::AddToBlocklist,
                        this,
                        &SomeUObjectClass::OnAddToBlocklistSuccess,
                        &SomeUObjectClass::OnAddToBlocklistFailed,
                        PlayerId);
}

void SomeUObjectClass::OnAddToBlocklistSuccess(FPgosResult Error)
{
      UE_LOG(LogTemp, Log, TEXT("OnAddToBlocklistSuccess"));
}

void SomeUObjectClass::OnAddToBlocklistFailed(FPgosResult Error)
{
      UE_LOG(LogTemp, Error, TEXT("OnAddToBlocklistFailed: err_code=%d, err_msg=%s"), Result.err_code, *Result.msg);
}

如果操作成功，目标玩家将出现在玩家的黑名单中。

3.3 从黑名单中移除

使用 RemoveFromBlocklist 函数从黑名单中移除玩家。

按照以下方式调用 Blocklist 模块中的 RemoveFromBlocklist：

UE C++
UE BP

#include "PgosSDKCpp.h"
#include "Core/PgosErrorCode.h"

void SomeUObjectClass::RemoveFromBlocklist()
{
    FString PlayerId = ObtainFromSomeWhere(); // The id for target player.
    auto blocklist = IPgosSDKCpp::Get().GetClientBlocklistAPI();
    if (blocklist)
    {
        blocklist->RemoveFromBlocklist(PlayerId, [](const FPgosResult& Ret) {
            if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
            {
                UE_LOG(LogTemp, Log, TEXT("OnRemoveFromBlocklistSuccess"));
            }
            else
            {
                UE_LOG(LogTemp, Log, TEXT("OnRemoveFromBlocklistFailed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
            }
        });
    }
}

#include "PgosClientBlocklistAPI.h"

void SomeUObjectClass::RemoveFromBlocklist()
{
    FString PlayerId = ObtainFromSomeWhere(); // The id for target player.
    PGOS_CALL_ASYNC_API(UPgosClientAPIRemoveFromBlocklist::RemoveFromBlocklist,
                        this,
                        &SomeUObjectClass::OnRemoveFromBlocklistSuccess,
                        &SomeUObjectClass::OnRemoveFromBlocklistFailed,
                        PlayerId);
}

void SomeUObjectClass::OnRemoveFromBlocklistSuccess(FPgosResult Error)
{
      UE_LOG(LogTemp, Log, TEXT("OnRemoveFromBlocklistSuccess"));
}

void SomeUObjectClass::OnRemoveFromBlocklistFailed(FPgosResult Error)
{
      UE_LOG(LogTemp, Error, TEXT("OnRemoveFromBlocklistFailed: err_code=%d, err_msg=%s"), Result.err_code, *Result.msg);
}

如果成功，该玩家将从玩家的黑名单中移除。

4. 使用黑名单服务（账号平台）

平台黑名单将用户的账号ID保存在平台中，需要通过调用'PgosClientFriendAPI::BatchAccountIDToPlayerID'接口将账号ID转换为PGOS中使用的玩家ID。

4.1 同步账号平台黑名单

接口原型：

/**
* Synchronize account platform blocklist to PGOS. The result returns the all blocklist
* 
* @param PlayerIds The player ids to Synchronize.
*/
void SyncAPBlocklist(
      const TArray<FString>& PlayerIds,
      TFunction<void(const FPgosResult& Ret, const FClientSyncAccountPlatformBlocklistResult* Data)> Callback) const;

示例代码:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
   auto Blocklist = IPgosSDKCpp::Get().GetClientBlocklistAPI();
   if (Blocklist)
   {
       TArray<FString> PlayerIds;
       Blocklist->SyncAPBlocklist(PlayerIds, [](const FPgosResult& Ret, const FClientSyncAccountPlatformBlocklistResult* Data) {
           if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
           {
               UE_LOG(LogTemp, Log, TEXT("SyncAPBlocklist Success"));
           }
           else
           {
               UE_LOG(LogTemp, Log, TEXT("SyncAPBlocklist Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
           }
       });
   }
}

4.2 同步新增账号平台黑名单

接口原型：

/**
* Synchronize added account platform blocklist to PGOS. 
* 
* @param PlayerId Added platform blocklist player to Synchronize.
*/
void SyncAPBlocklistAdded(
      const FString& PlayerId,
      TFunction<void(const FPgosResult& Ret)> Callback) const;

示例代码:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
   auto Blocklist = IPgosSDKCpp::Get().GetClientBlocklistAPI();
   if (Blocklist)
   {
       FString PlayerId;
       Blocklist->SyncAPBlocklistAdded(PlayerId, [](const FPgosResult& Ret) {
           if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
           {
               UE_LOG(LogTemp, Log, TEXT("SyncAPBlocklistAdded Success"));
           }
           else
           {
               UE_LOG(LogTemp, Log, TEXT("SyncAPBlocklistAdded Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
           }
       });
   }
}

4.3 同步已删除账号平台黑名单

接口原型：

/**
* Synchronize removed account platform blocklist to PGOS. 
* 
* @param PlayerId Removed platform blocklist player to Synchronize.
*/
void SyncAPBlocklistRemoved(
      const FString& PlayerId,
      TFunction<void(const FPgosResult& Ret)> Callback) const;

示例代码:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
   auto Blocklist = IPgosSDKCpp::Get().GetClientBlocklistAPI();
   if (Blocklist)
   {
       FString PlayerId;
       Blocklist->SyncAPBlocklistRemoved(PlayerId, [](const FPgosResult& Ret) {
           if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
           {
               UE_LOG(LogTemp, Log, TEXT("SyncAPBlocklistRemoved Success"));
           }
           else
           {
               UE_LOG(LogTemp, Log, TEXT("SyncAPBlocklistRemoved Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
           }
       });
   }
}

4.4 同步账号平台语音黑名单

接口原型：

/**
* Synchronize account platform voice blocklist to PGOS. For platforms with voice blocklist such as XBOX
* 
* @param PlayerIds The player ids to Synchronize.
*/
void SyncAPVoiceBlocklist(
      const TArray<FString>& PlayerIds,
      TFunction<void(const FPgosResult& Ret)> Callback) const;

示例代码:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
   auto Blocklist = IPgosSDKCpp::Get().GetClientBlocklistAPI();
   if (Blocklist)
   {
       TArray<FString> PlayerIds;
       Blocklist->SyncAPVoiceBlocklist(PlayerIds, [](const FPgosResult& Ret) {
           if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
           {
               UE_LOG(LogTemp, Log, TEXT("SyncAPVoiceBlocklist Success"));
           }
           else
           {
               UE_LOG(LogTemp, Log, TEXT("SyncAPVoiceBlocklist Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
           }
       });
   }
}

1. 概述​

2. 功能特性​

2.1 游戏内黑名单​

2.2 账号平台黑名单​

3. 使用黑名单服务(游戏内)​

3.1 获取黑名单​

3.2 添加至黑名单​

3.3 从黑名单中移除​

4. 使用黑名单服务（账号平台）​

4.1 同步账号平台黑名单​

4.2 同步新增账号平台黑名单​

4.3 同步已删除账号平台黑名单​

4.4 同步账号平台语音黑名单​

1. 概述

2. 功能特性

2.1 游戏内黑名单

2.2 账号平台黑名单

3. 使用黑名单服务(游戏内)

3.1 获取黑名单

3.2 添加至黑名单

3.3 从黑名单中移除

4. 使用黑名单服务（账号平台）

4.1 同步账号平台黑名单

4.2 同步新增账号平台黑名单

4.3 同步已删除账号平台黑名单

4.4 同步账号平台语音黑名单