Epic Online Services Unreal Blueprint Login Hataları ve Achievement Hataları Nasıl Düzeltilir

Unreal Engine oyununuzun bir shipping build'ini derleyip Epic Games Launcher üzerinden başlattıktan sonra özel login butonunuza tıklıyorsunuz. Ya hiçbir şey olmuyor ya da oyun istemcisi donuyor ve log dosyalarınız karmaşık authentication hatası bildirimleriyle doluyor. Daha da kötüsü, achievement unlock node'unuz görünürde hiçbir hata vermeden çalışıyor, ancak oyuncunun Epic Games Store overlay'indeki profili tamamen boş kalıyor. Bu hatalar, mağaza API entegrasyonları yaparken son derece yaygındır. Neyse ki, asenkron execution flow'u düzelterek ve Online Subsystem'in kullanıcı kimliklerini nasıl eşlediğini anlayarak bu sorunları çözebilirsiniz.

EOS Authentication Pipeline Mantığını Anlamak: EAID vs. PUID

Epic Online Services (EOS) entegrasyonunu Unreal Engine'in Online Subsystem (OSS) altyapısı üzerinden yapmak, iki katmanlı bir kimlik doğrulama sisteminde gezinmeyi gerektirir. Epic Account ID (EAID), Auth Interface tarafından yönetilir. Kullanıcının mağaza düzeyindeki kimliğini doğrulayarak social overlay, arkadaş listeleri ve Epic Games Store kütüphane kontrolleri gibi özellikleri etkinleştirir.

Buna karşılık, Product User ID (PUID) ise Connect Interface tarafından yönetilir. PUID, kullanıcıyı oyunun backend servislerine bağlayan oyuna özel bir kimlik tanımlayıcıdır. Bu servisler arasında matchmaking, stats, cloud saves ve achievements yer alır.

EAID ve PUID Uyuşmazlıkları Achievements Özelliğini Neden Bozar?

Geliştiricilerin Auth Interface ile başarılı bir şekilde kimlik doğrulaması yapıp (EAID oluşturarak) Online Subsystem'in Connect Interface üzerinde login işlemlerini gerçekleştirememesi, sıkça karşılaşılan bir hata senaryosudur. Achievements sistemi, PUID kullanan Connect Interface tarafından yönetildiğinden, çözümlenmiş (resolved) bir PUID olmadan achievement ilerlemesi yazmaya çalışmak EOS_InvalidUser hatasıyla sonuçlanır.

Herhangi bir mağaza istemcisi (storefront wrapper) olmadan açılan oyunlarda kullanıcılar genellikle merkezi bir kullanıcı tablosuna göre doğrulanan credentials (kimlik bilgileri) ile login olurlar. Epic Games Store gibi modern mağaza ekosistemlerinde ise kimlik doğrulama federe (federated) bir yapıya sahiptir. Oyununuz başladığında launcher'dan kriptografik bir bilet (ticket) alır. Ardından oyun bu bileti mağazanın authentication sunucularına iletir. SDK, kullanıcının platformdaki tüm oyunlarda pasaportu işlevini gören bir Epic Account ID döndürür.

Ancak Epic, gizliliği ve cross-play güvenliğini korumak amacıyla achievements gibi oyuna özel özelliklerin doğrudan Epic Account ID'yi okumasına izin vermez. Bunun yerine oyunun, Product User ID değerini almak için ikincil bir doğrulama gerçekleştiren Connect Interface yapısını initialize etmesi gerekir. Bu ayrım, oyununuz hacklense bile oyuncuların genel Epic Account credentials bilgilerinin tehlikeye girmemesini sağlar. PUID olmadan oyununuz fiilen doğrulanmamış bir guest (misafir) durumunda çalışır ve EGS özelliklerine erişim engellenir. Eğer credentials config dosyanızda veya client policy ayarlarınızda Epic Developer Portal üzerinde doğru izinler tanımlanmadıysa, bu eşleşme başarısız olur. Kimlik arayüzü (identity interface), Epic hesabı geçerli olduğu için başarılı bir login bildirir; ancak hiçbir PUID bağlanamadığı için oyun servisleri katmanı achievement verilerini yazamaz.

Hatalı Bir Blueprint Login Diziliminin Anatomisi

Pek çok geliştirici, Blueprint execution pin'lerini doğrusal olarak birbirine bağladığı için login sorunlarıyla karşılaşır. Execution pin'i doğrudan bir Login node'undan Query Achievements veya Write Achievement Progress node'una sürüklemek her zaman başarısızlıkla sonuçlanır.

Authentication isteklerinin Epic backend sistemine ulaşması gerektiğinden, bu işlemler asenkron olarak çalışır. Oyun motoru, Epic sunucuları kullanıcı credentials bilgilerini döndürmeden çok daha önce, hemen bir sonraki frame'de Blueprint graph'ını yürütmeye devam eder. Bu aşamada oyuncunun Unique Net ID değeri henüz null (boş) durumdadır.

"Eksik Node" Uyuşmazlığı: Async Execution Sırasındaki Race Condition Durumları

Eğer login node'unun hemen ardından achievement node'larını çağırırsanız, önbelleğe alınmış (cached) kullanıcı durumu boş olduğundan Online Subsystem arka planda sessizce bir hata verir. Doğru iş akışı için custom event'lerin subsystem'in asenkron delegate'lerine bind edilmesi gerekir.

Ayrıca, geliştiriciler genellikle achievement verilerini yazmadan önce önbelleğe alma (caching) adımını gözden kaçırırlar. Mevcut şema için sunucuya sorgu yapmadan bir achievement'ın ilerlemesini değiştiremezsiniz. Öncesinde bir Query Achievements çağrısı yapmadan doğrudan Write Achievements çağırmak, yerel önbellekteki achievement map boyutu 0 olduğu için sessiz bir başarısızlığa veya konsol logunuzda EOS_InvalidUser hatasına neden olur.

Doğru Asenkron Blueprint Akışı

Bu sorunu çözmek için login tetikleyicisi ile achievement güncellemesini birbirinden ayırmalısınız. İlk olarak, login node'unu çağırın ve doğru authentication credentials bilgilerini belirtin.

İkinci olarak, identity interface'in On Login Complete delegate'ine bir event bind edin. Bu event tetiklendiğinde ve başarılı bir durum döndürdüğünde, kullanıcının Unique Net ID'sini alın.

Üçüncü olarak, bu ID'yi Query Achievements node'una aktarın. Son olarak, On Query Achievements Complete delegate'ine bir event bind edin ve Write Achievement Progress node'unu yalnızca bu callback içerisinden çağırın.

C++ ile Güçlü Bir EOS Login ve Achievement Controller Geliştirmek

Bu asenkron operasyonları temiz bir şekilde yönetmek için authentication döngüsünün C++ tarafında kurulması şiddetle önerilir. C++, IOnlineSubsystem ve arayüzlerine doğrudan erişim sağlar.

Aşağıda, login ve achievement yönetimi için eksiksiz ve production-ready bir C++ implementasyonu yer almaktadır:

#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."));
    }
}

Bu controller, ardışık callback'leri kullanır. Achievement arayüzüne (achievement interface) yalnızca identity interface hem Epic Account ID hem de Product User ID değerlerini başarıyla çözümledikten sonra erişilmesini garanti eder.

EOS için DefaultEngine.ini Dosyasını Yapılandırmak

Config/DefaultEngine.ini dosyanızdaki yapılandırmalar yanlışsa, Blueprint login node'ları initialize edilemeyecektir. Online Subsystem EOS eklentisi (plugin), oyun istemcinize bağlanmak için belirli parametrelere ihtiyaç duyar.

Subsystem'inizin düzgün şekilde initialize edilmesini sağlamak için aşağıdaki yapılandırma şablonunu kullanın:

[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

DefaultEngine.ini dosyanızın yapılandırması, derlenmiş oyun binary dosyalarınız ile Epic Developer Portal arasında bir köprü görevi görür. [OnlineSubsystemEOS] altındaki parametreler, ürün ayarlarınızla (product settings) birebir eşleşmelidir.

Sıkça karşılaşılan kafa karışıklıklarından biri, client credentials ile sandbox ID'leri arasındaki farktır. Client ID ve Client Secret, oyun istemcinizin credentials bilgilerini temsil eder ve onun EOS backend altyapısı ile iletişim kurmasını sağlar. Sandbox ID ise istemcinizin eriştiği belirli ortamı (Development, Staging veya Live gibi) temsil eder.

Oyun istemciniz, Client Credentials politikası ile eşleşmeyen bir Sandbox ID ile authenticate olmaya çalışırsa, authentication isteği reddedilecektir. Ek olarak, Online Subsystem'in arka planda EAID-to-PUID eşlemesini otomatik olarak yapmasını sağlamak için bUseEpicConnect bayrağının (flag) true olarak ayarlanması gerekir.

Overlay Odaklanma Sorunlarını ve Platform Entegrasyonunu Yönetmek

Unreal'in EOS eklentisi (plugin), bildirimleri göstermek, arkadaş davetlerini yönetmek ve OAuth web kimlik doğrulamalarını gerçekleştirmek için büyük ölçüde Epic Games Overlay sistemine dayanır. Oyun istemciniz AccountPortal credential türünü kullanarak bir login tetiklediğinde, işletim sistemi bir tarayıcı penceresi başlatır veya overlay'i açar.

Bu yönlendirme, odağı oyun penceresinden uzaklaştırır. Eğer input modlarınız odak kaybını (focus loss) yönetecek şekilde ayarlanmamışsa, oyun kilitlenebilir veya tuşlar basılı kalmış gibi davranabilir.

Overlay kaynaklı input sorunlarıyla uğraşmak, PC geliştiricileri için yaygın bir baş ağrısıdır. Örneğin overlay injection, raw input driver'ları ile çakışabilir ve klavye/fare durumlarının donmasına neden olabilir. Bu hataların oyuncu deneyimini baltalamasını önlemek için The Marathon Input Issues Fix: Architecting PC Games to Survive Overlay Conflicts hakkındaki analizimizi inceleyebilirsiniz.

Ayrıca, test sırasındaki initialization hataları genellikle yerel yapılandırmanızdaki yanlış yapılandırılmış socket connection'lar veya timeout eşiklerinden kaynaklanır. Eğer session başlangıcında (session startup) driver timeout sorunlarını gidermeye çalışıyorsanız, Uefn Session Launch Timeout Nightmares: Diagnosing Unreal Engine Network Drivers kılavuzumuza göz atabilirsiniz.

Cross-Platform Mağaza Backend Yapılarını Sadeleştirmek

Mağaza subsystem'lerini manuel olarak yapılandırmak, C++ delegate zincirleri yazmak ve platforma özgü overlay odaklanma sorunlarıyla uğraşmak son derece zaman alıcıdır. Bunu Steam, EGS ve konsollar gibi birden fazla mağaza için yapmak geliştirme yükünüzü (development overhead) katlar.

Bunu kendi başınıza inşa etmek; load balancer'lar kurmayı, database sharding yapılandırmayı ve SSL cert yönetimini (SSL cert management) gerektirir ki bu da kolayca 4-6 haftalık bir iş demektir.

horizOn ile, bu mağaza API'lerini soyutlayan birleşik bir cross-platform backend elde edersiniz. Çift kimlikli token'lar (EAID/PUID), Epic sandbox'ları veya Steamworks initialization kodlarıyla uğraşmak yerine; kullanıcı profillerini, achievements sistemini, matchmaking ve leaderboard'ları yöneten tek bir API kullanırsınız.

horizOn, bir köprü görevi görerek achievements ve oyuncu ilerlemesini kullanıcının oyunu başlattığı mağaza ile otomatik olarak senkronize eder; böylece mağaza boilerplate kodları yerine doğrudan game loop'a odaklanabilirsiniz. Bu, oyuncularınızın hangi platformu veya launcher'ı kullanırlarsa kullansınlar, sizin mağazaya özel tek bir satır SDK kodu yazmanıza gerek kalmadan achievements kilidini açabilmesi, cloud saves erişimi sağlayabilmesi ve maç arayabilmesi (matchmaking) anlamına gelir.

Epic Online Services Entegrasyonları İçin Modern En İyi Pratikler

1. Asenkron Node'ları Asla Doğrudan Birbirine Bağlamayın: Stats veya achievements yazmak gibi sonraki işlemleri çalıştırmadan önce her zaman OnLoginComplete ve OnQueryAchievementsComplete delegate'lerinin tetiklenmesini bekleyin.

2. Geliştirme Sırasında Verbose Logging'i Etkinleştirin: Gizli EOS uyarılarını takip etmek için DefaultEngine.ini dosyanızdaki [Core.Log] alanının altına aşağıdaki satırları ekleyin:

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

3. Achievements Verilerini Dev Portal'da EOS ile Eşleyin: Epic Games Store (EGS) altında oluşturulan achievements'ların Epic Online Services (EOS) backend sisteminizle açıkça eşlendiğinden emin olun. Eğer bağlı değillerse, EOS SDK bu achievement ID'sini tanımayacaktır.

4. Shipping Build Sürümlerinde ExchangeCode Kullanın: Yerel geliştirme sırasında Dev Auth Tool içeren Developer login türü pratiktir; ancak Epic Games Launcher'dan başlatılan shipping build'lerde credentials türünü ExchangeCode olarak değiştirmelisiniz. Launcher tarafından sağlanan ExchangeCode auth türünü kullanmak, web tarayıcısı OAuth yönlendirmesini atlayarak login süresini 8-12 saniyelik manuel kullanıcı etkileşiminden 500 ms'nin altındaki otomatik bir handshake işlemine indirir.

Mağaza Entegrasyonlarını Kolaylaştırmak

Unreal Engine'de Epic Online Services login ve achievement hatalarını çözmek, asenkron pipeline yapısını anlamaktan ve yapılandırma profillerini kusursuz bir şekilde hizalamaktan geçer. Geliştiriciler, identity ve game service arayüzleri arasındaki geçişi yöneterek sessiz hataları ortadan kaldırabilir ve kesintisiz bir oyuncu deneyimi sunabilir.

Multiplayer backend yapınızı ölçeklendirmeye hazır mısınız? horizOn'u ücretsiz deneyin veya API dökümanlarına göz atın.

---

Kaynak: Epic Games Store (Online Services AND Achievements)