Cara Mengatasi Kegagalan Login Blueprint Unreal dan Error Achievement pada Epic Online Services

Anda melakukan kompilasi shipping build dari game Unreal Engine Anda, menjalankannya dari Epic Games Launcher, dan mengeklik tombol login kustom Anda. Tidak terjadi apa-apa, atau game client mendadak freeze, dan log Anda dipenuhi dengan notifikasi kegagalan autentikasi yang samar. Lebih buruk lagi, node unlock achievement Anda berjalan tanpa menampilkan error apa pun, namun profil pemain di overlay Epic Games Store tetap kosong. Error seperti ini sangat umum terjadi saat mengintegrasikan API storefront. Untungnya, masalah ini dapat diselesaikan dengan memperbaiki asynchronous execution flow Anda dan memahami bagaimana subsistem memetakan identitas pengguna.

Understanding the EOS Authentication Pipeline: EAID vs. PUID

Mengintegrasikan Epic Online Services (EOS) melalui Online Subsystem (OSS) milik Unreal Engine memerlukan navigasi sistem identitas dua lapis. Epic Account ID (EAID) dikelola oleh Auth Interface. Interface ini memvalidasi siapa pengguna tersebut di level storefront, mengaktifkan fitur seperti social overlay, daftar teman, dan pemeriksaan library Epic Games Store.

Sebaliknya, Product User ID (PUID) dikelola oleh Connect Interface. PUID adalah pengidentifikasi spesifik-game yang menghubungkan pengguna ke backend game services. Layanan ini mencakup matchmaking, stats, cloud saves, dan achievements.

Why EAID and PUID Mismatches Break Achievements

Failure mode yang sering terjadi adalah ketika developer berhasil melakukan autentikasi dengan Auth Interface (menghasilkan EAID), tetapi subsistem gagal login ke Connect Interface. Karena achievements dikelola oleh Connect Interface menggunakan PUID, menulis progress achievement tanpa PUID yang valid akan gagal dengan error EOS_InvalidUser.

Pada game yang berjalan tanpa storefront wrapper, pengguna biasanya login menggunakan kredensial yang dicocokkan dengan tabel pengguna terpusat. Dalam ekosistem storefront modern seperti Epic Games Store, identitas bersifat terfederasi. Saat game Anda dijalankan, game akan menerima tiket kriptografis dari launcher. Game kemudian meneruskan tiket ini ke server autentikasi storefront. SDK akan mengembalikan Epic Account ID, yang berfungsi sebagai paspor pengguna di semua game dalam platform tersebut.

Namun, untuk menjaga privasi dan keamanan cross-play, Epic tidak mengizinkan fitur spesifik-game seperti achievements untuk membaca Epic Account ID secara langsung. Sebagai gantinya, game harus menginisialisasi Connect Interface, yang melakukan pertukaran sekunder untuk mendapatkan Product User ID. Pemisahan ini memastikan bahwa jika game Anda diretas, kredensial Epic Account global pemain tidak akan terkompromi. Tanpa PUID, game Anda secara praktis beroperasi dalam unauthenticated guest state, yang memblokir akses ke fitur-fitur EGS. Jika konfigurasi kredensial atau client policy Anda tidak memiliki permission yang tepat di Epic Developer Portal, koneksi ini akan gagal. Identity interface akan melaporkan login yang berhasil karena akun Epic tersebut valid, tetapi lapisan game services tidak dapat menulis data achievement karena tidak ada PUID yang terhubung.

The Anatomy of a Broken Blueprint Login Sequence

Banyak developer menghadapi masalah login karena menghubungkan pin eksekusi Blueprint secara linear. Menarik pin eksekusi dari node Login langsung ke node Query Achievements atau Write Achievement Progress akan selalu gagal.

Permintaan autentikasi harus dikirim ke backend Epic, menjadikannya bersifat asynchronous. Engine akan terus mengeksekusi graph Blueprint pada frame berikutnya, jauh sebelum server Epic mengembalikan kredensial pengguna. Pada tahap ini, Unique Net ID pemain masih bernilai null.

The "Missing Node" Mismatch: Race Conditions in Async Execution

Jika Anda memanggil node achievement segera setelah node login, subsistem akan memicu silent error karena cached user state masih kosong. Alur kerja yang benar memerlukan pengikatan (binding) custom event ke asynchronous delegate milik subsistem.

Selain itu, developer sering kali melewatkan langkah krusial untuk melakukan caching achievements sebelum menulis progress ke dalamnya. Anda tidak dapat mengubah progress achievement tanpa terlebih dahulu melakukan query ke server untuk mengambil skema saat ini. Memanggil Write Achievements tanpa didahului panggilan Query Achievements akan menyebabkan silent failure atau error EOS_InvalidUser pada log konsol Anda karena ukuran local cached achievement map bernilai 0.

The Correct Asynchronous Blueprint Flow

Untuk mengatasinya, Anda harus memisahkan pemicu login dari pembaruan achievement. Pertama, panggil node login dan tentukan kredensial autentikasi yang benar.

Kedua, hubungkan event ke delegate On Login Complete dari identity interface. Setelah event ini aktif dan mengembalikan status sukses, ambil Unique Net ID pengguna.

Ketiga, masukkan ID ini ke dalam node Query Achievements. Terakhir, hubungkan event ke delegate On Query Achievements Complete, dan panggil Write Achievement Progress hanya di dalam callback tersebut.

Implementing a Robust EOS Login & Achievement Controller in C++

Untuk menangani operasi asynchronous ini secara bersih, mengimplementasikan loop autentikasi dalam C++ sangat direkomendasikan. Ini memberikan akses langsung ke IOnlineSubsystem beserta interface-nya.

Berikut adalah implementasi C++ lengkap dan siap produksi untuk menangani login dan achievement:

#include "OnlineSubsystem.h"
#include "Interfaces/OnlineIdentityInterface.h"
#include "Interfaces/OnlineAchievementsInterface.h"
#include "OnlineSubsystemUtils.h"

void UEOSLoginHandler::LoginToEpicGames(APlayerController* PlayerController)

{
    if (!PlayerController) return;

    IOnlineSubsystem* Subsystem = IOnlineSubsystem::Get(TEXT("EOS"));
    if (!Subsystem)
    {
        UE_LOG(LogTemp, Warning, TEXT("EOS Subsystem not found. Make sure the plugin is enabled."));
        return;
    }

    IOnlineIdentityPtr Identity = Subsystem->GetIdentityInterface();
    if (Identity.IsValid())
    {
        FOnlineAccountCredentials Credentials;
        Credentials.Type = TEXT("ExchangeCode");
        Credentials.Id = TEXT("");
        Credentials.Token = TEXT(""); // The launcher passes this via command line arguments

        Identity->AddOnLoginCompleteDelegate_Handle(0, FOnLoginCompleteDelegate::CreateUObject(this, &UEOSLoginHandler::OnLoginComplete));
        Identity->Login(0, Credentials);
    }
}

void UEOSLoginHandler::OnLoginComplete(int32 LocalUserNum, bool bWasSuccessful, const FUniqueNetId& UserId, const FString& Error)
{
    if (!bWasSuccessful)
    { 
        UE_LOG(LogTemp, Error, TEXT("Epic Online Services Login Failed. Error: %s"), *Error);
        return;
    }

    UE_LOG(LogTemp, Log, TEXT("EOS Login Successful. ID resolved: %s"), *UserId.ToString());

    IOnlineSubsystem* Subsystem = IOnlineSubsystem::Get(TEXT("EOS"));
    IOnlineAchievementsPtr Achievements = Subsystem->GetAchievementsInterface();
    if (Achievements.IsValid())
    { 
        Achievements->QueryAchievements(UserId, FOnQueryAchievementsCompleteDelegate::CreateUObject(this, &UEOSLoginHandler::OnQueryAchievementsComplete));
    }
}

void UEOSLoginHandler::OnQueryAchievementsComplete(const FUniqueNetId& PlayerId, bool bWasSuccessful)
{
    if (!bWasSuccessful)
    {
        UE_LOG(LogTemp, Warning, TEXT("Failed to query achievements from Epic Developer Portal."));
        return;
    }

    UE_LOG(LogTemp, Log, TEXT("Achievements queried successfully. Now writing progress."));

    IOnlineSubsystem* Subsystem = IOnlineSubsystem::Get(TEXT("EOS"));
    IOnlineAchievementsPtr Achievements = Subsystem->GetAchievementsInterface();
    if (Achievements.IsValid())
    {
        FOnlineAchievementsWriteRef WriteObject = MakeShared<FOnlineAchievementsWrite>();
        WriteObject->SetFloatStat(TEXT("ACH_FIRST_BLOOD"), 100.0f);

        Achievements->WriteAchievements(PlayerId, WriteObject, FOnAchievementsWrittenDelegate::CreateUObject(this, &UEOSLoginHandler::OnAchievementsWritten));
    }
}

void UEOSLoginHandler::OnAchievementsWritten(const FUniqueNetId& PlayerId, bool bWasSuccessful)
{
    if (bWasSuccessful)
    {
        UE_LOG(LogTemp, Log, TEXT("Achievement successfully unlocked on Epic Games Store!"));
    }
    else
    {
        UE_LOG(LogTemp, Error, TEXT("Failed to write achievement progress. Check sandbox mappings."));
    }
}

Controller ini menggunakan callback berurutan. Ini memastikan bahwa achievement interface hanya diakses setelah identity interface berhasil menyelesaikan pemetaan Epic Account ID dan Product User ID.

Configuring your DefaultEngine.ini File for EOS

Node login Blueprint akan gagal diinisialisasi jika konfigurasi pada file Config/DefaultEngine.ini Anda salah. Plugin Online Subsystem EOS memerlukan parameter khusus agar dapat terhubung dengan game client Anda.

Gunakan templat konfigurasi berikut untuk memastikan subsistem Anda terinisialisasi dengan benar:

[OnlineSubsystem]
DefaultPlatformService=EOS

[OnlineSubsystemEOS]
bEnabled=true
bUseEpicConnect=true
ProductId=your_product_id_here
SandboxId=your_sandbox_id_here
DeploymentId=your_deployment_id_here
ClientId=your_client_id_here
ClientSecret=your_client_secret_here

[OnlineSubsystemEOS.Auth]
bUseEpicAccount=true

Konfigurasi file DefaultEngine.ini Anda bertindak sebagai jembatan antara biner game hasil kompilasi dan Epic Developer Portal. Parameter di bawah [OnlineSubsystemEOS] harus cocok persis dengan pengaturan produk Anda.

Sumber kebingungan yang sering terjadi adalah perbedaan antara client credentials dan sandbox ID. Client ID dan Client Secret mewakili kredensial dari game client Anda, yang memungkinkannya berkomunikasi dengan backend EOS. Sedangkan Sandbox ID mewakili lingkungan spesifik (seperti Development, Staging, atau Live) yang sedang diakses oleh client Anda.

Jika game client Anda mencoba melakukan autentikasi dengan Sandbox ID yang tidak cocok dengan kebijakan Client Credentials, permintaan autentikasi tersebut akan ditolak. Selain itu, flag bUseEpicConnect harus diatur ke true untuk memastikan Online Subsystem menangani pemetaan EAID-ke-PUID secara otomatis di balik layar.

Managing Overlay Focus Mismatches and Platform Integration

Plugin EOS Unreal sangat bergantung pada Epic Games Overlay untuk menampilkan notifikasi, menangani undangan teman, dan melakukan autentikasi web OAuth. Ketika game client memicu login menggunakan jenis kredensial AccountPortal, sistem operasi akan membuka jendela browser atau mengaktifkan overlay.

Pengalihan (redirection) ini menggeser fokus dari jendela game. Jika input mode Anda tidak dikonfigurasi untuk menangani hilangnya fokus, game bisa macet atau mendeteksi tombol keyboard yang tertahan (stuck keys).

Menangani masalah input yang disebabkan oleh overlay adalah hal yang sering memusingkan bagi PC developer. Sebagai contoh, overlay injection dapat berkonflik dengan raw input driver dan menyebabkan input keyboard/mouse mendadak freeze. Untuk mencegah bug semacam ini merusak pengalaman pemain, Anda dapat membaca analisis kami di The Marathon Input Issues Fix: Architecting PC Games to Survive Overlay Conflicts.

Selain itu, kegagalan inisialisasi selama pengujian sering kali disebabkan oleh kesalahan konfigurasi koneksi socket atau batas waktu (timeout threshold) pada konfigurasi lokal Anda. Jika Anda sedang melakukan troubleshooting driver timeout saat session startup, pelajari panduan kami di Uefn Session Launch Timeout Nightmares: Diagnosing Unreal Engine Network Drivers.

Simplifying Cross-Platform Storefront Backends

Mengonfigurasi subsistem storefront secara manual, menulis rangkaian delegate C++, dan menangani masalah fokus overlay spesifik-platform sangat memakan waktu. Melakukan hal ini untuk berbagai storefront seperti Steam, EGS, dan konsol akan melipatgandakan development overhead Anda.

Membangun infrastruktur ini sendiri mengharuskan Anda menyiapkan load balancer, sharding database, dan manajemen sertifikat SSL — yang bisa memakan waktu hingga 4-6 minggu pengerjaan.

Dengan horizOn, Anda mendapatkan backend lintas platform terpadu yang mengabstraksi API storefront ini. Alih-alih berurusan dengan token identitas ganda (EAID/PUID), sandbox Epic, atau kode inisialisasi Steamworks, Anda cukup menggunakan satu API tunggal yang menangani profil pengguna, achievements, matchmaking, dan leaderboards.

horizOn bertindak sebagai jembatan yang menyinkronkan achievements dan progres pemain secara otomatis ke storefront mana pun yang digunakan pengguna saat game dijalankan, memungkinkan Anda fokus pada game loop alih-alih boilerplate code storefront. Ini berarti pemain Anda dapat membuka achievements, mengakses cloud saves, dan mencari match tanpa peduli platform atau launcher apa yang mereka gunakan, tanpa Anda harus menulis satu baris pun kode SDK spesifik-storefront.

Modern Best Practices for Epic Online Services Integrations

1. Jangan Pernah Menghubungkan Node Asynchronous secara Langsung: Selalu tunggu delegate OnLoginComplete dan OnQueryAchievementsComplete dipicu sebelum menjalankan operasi lanjutan (downstream) seperti menulis statistik atau achievements.

2. Aktifkan Verbose Logging Selama Pengembangan: Tambahkan baris berikut ke DefaultEngine.ini Anda di bawah [Core.Log] untuk melacak peringatan EOS yang tersembunyi:

   [Core.Log]
   LogOnline=VeryVerbose
   LogOnlineGame=VeryVerbose
   LogEOSSDK=VeryVerbose
   

3. Petakan Achievements ke EOS di Dev Portal: Pastikan bahwa achievements yang dibuat di bawah Epic Games Store (EGS) telah dipetakan secara eksplisit ke backend Epic Online Services (EOS) Anda. Jika tidak terhubung, EOS SDK tidak akan mengenali ID achievement tersebut.

4. Gunakan ExchangeCode pada Shipping Builds: Selama pengembangan lokal, jenis login Developer dengan Dev Auth Tool sangat memudahkan, tetapi Anda harus mengubah tipe kredensial menjadi ExchangeCode pada shipping builds yang dijalankan dari Epic Games Launcher. Menggunakan metode autentikasi ExchangeCode yang disediakan oleh launcher akan melewati pengalihan OAuth browser web, memangkas durasi urutan login dari 8-12 detik interaksi manual menjadi automated handshake di bawah 500 milidetik.

Streamlining Storefront Integrations

Mengatasi error login dan achievement pada Epic Online Services di Unreal Engine intinya adalah memahami async pipeline dan memastikan profil konfigurasi selaras dengan sempurna. Dengan mengelola transisi antara identity interface dan game service interface, developer dapat menghilangkan silent errors dan menghadirkan pengalaman bermain yang mulus bagi pemain.

Siap untuk melakukan scaling pada backend multiplayer Anda? Coba horizOn secara gratis atau pelajari API docs kami.

---

Source: Epic Games Store (Online Services AND Achievements)