Hoe je Epic Online Services Unreal Blueprint login-problemen en achievement-fouten oplost

Je compileert een shipping build van je Unreal Engine-game, start deze op vanuit de Epic Games Launcher en klikt op je custom login-knop. Er gebeurt niets, of de game client loopt vast, en je logs stromen vol met cryptische authentication failure-meldingen. Nog erger is dat je achievement unlock-node wordt uitgevoerd zonder zichtbare foutmeldingen te tonen, terwijl het profiel van de speler in de Epic Games Store-overlay volledig leeg blijft. Deze fouten komen ontzettend vaak voor bij het integreren van storefront API's. Gelukkig kunnen ze worden opgelost door je asynchrone execution flow te corrigeren en te begrijpen hoe het subsystem user identities mapt.

De EOS-authenticatie-pipeline begrijpen: EAID vs. PUID

Het integreren van Epic Online Services (EOS) via de Online Subsystem (OSS) van Unreal Engine vereist dat je navigeert door een identity-systeem met twee lagen. De Epic Account ID (EAID) wordt beheerd door de Auth Interface. Deze valideert wie de gebruiker is op storefront-niveau en maakt features zoals de sociale overlay, vriendenlijsten en Epic Games Store-bibliotheekcontroles mogelijk.

Daarentegen wordt de Product User ID (PUID) beheerd door de Connect Interface. De PUID is een game-specifieke identifier die de gebruiker koppelt aan backend game services. Deze services omvatten matchmaking, stats, cloud saves en achievements.

Waarom EAID- en PUID-mismatches achievements breken

Een veelvoorkomende failure mode treedt op wanneer developers succesvol authenticeren met de Auth Interface (wat een EAID genereert), maar het subsystem er niet in slaagt in te loggen op de Connect Interface. Omdat achievements via PUID's worden beheerd door de Connect Interface, faalt het wegschrijven van achievement-voortgang zonder een opgeloste PUID met een EOS_InvalidUser-foutmelding.

In games die zonder storefront-wrapper worden gelanceerd, loggen gebruikers doorgaans in met credentials die worden gecontroleerd tegen een gecentraliseerde gebruikerstabel. In een modern storefront-ecosysteem zoals de Epic Games Store is identity gefedereerd. Wanneer je game start, ontvangt deze een cryptografisch ticket van de launcher. De game stuurt dit ticket vervolgens door naar de authenticatieservers van de storefront. De SDK retourneert een Epic Account ID, die fungeert als het paspoort van de gebruiker voor alle games op het platform.

Om privacy en cross-play-beveiliging te waarborgen, staat Epic echter niet toe dat game-specifieke features zoals achievements de Epic Account ID rechtstreeks uitlezen. In plaats daarvan moet de game de Connect Interface initialiseren, die een secundaire uitwisseling uitvoert om een Product User ID op te halen. Deze scheiding zorgt ervoor dat als je game wordt gehackt, de wereldwijde Epic Account-credentials van spelers niet in gevaar komen. Zonder de PUID bevindt je game zich in feite in een niet-geauthenticeerde gaststatus, wat de toegang tot EGS-features blokkeert. Als je credentials-config of client policy niet de juiste machtigingen heeft in de Epic Developer Portal, faalt deze koppeling. De identity-interface meldt een succesvolle login omdat het Epic-account geldig is, maar de game services-laag kan geen achievement-data wegschrijven omdat er nooit een PUID is gekoppeld.

De anatomie van een defecte Blueprint login-sequence

Veel developers lopen tegen login-problemen aan doordat ze hun Blueprint execution pins lineair aan elkaar koppelen. Het rechtstreeks verslepen van de execution pin van een Login-node naar een Query Achievements- of Write Achievement Progress-node zal altijd falen.

Authenticatieverzoeken moeten naar de Epic-backend reizen, waardoor ze asynchroon zijn. De engine gaat al in de allereerste volgende frame verder met het uitvoeren van de Blueprint-graph, lang voordat de Epic-servers de user credentials retourneren. In deze fase blijft de Unique Net ID van de speler null.

De "Missing Node"-mismatch: race conditions in asynchrone uitvoering

Als je direct na de login-node achievement-nodes aanroept, werpt het subsystem een stille foutmelding op omdat de gecachte user state leeg is. De juiste workflow vereist dat je custom events bindt aan de asynchrone delegates van het subsystem.

Bovendien missen developers vaak de cruciale stap om achievements te cachen voordat ze er naartoe schrijven. Je kunt de voortgang van een achievement niet aanpassen zonder eerst de server te queryen voor het huidige schema. Het aanroepen van Write Achievements zonder een voorafgaande Query Achievements-aanroep resulteert in een silent failure of een EOS_InvalidUser-foutmelding in je console-log, omdat de grootte van de lokale gecachte achievement-map 0 is.

De juiste asynchrone Blueprint-flow

Om dit op te lossen, moet je de login-trigger scheiden van de achievement-update. Roep eerst de login-node aan en geef de juiste authenticatie-credentials op.

Koppel vervolgens een event aan de On Login Complete-delegate van de identity-interface. Zodra dit event wordt getriggerd en een successtatus retourneert, haal je de Unique Net ID van de gebruiker op.

Geef vervolgens dit ID door aan de Query Achievements-node. Bind ten slotte een event aan de On Query Achievements Complete-delegate en roep Write Achievement Progress pas aan binnen die callback.

Een robuuste EOS Login & Achievement Controller implementeren in C++

Om deze asynchrone bewerkingen netjes af te handelen, is het ten zeerste aanbevolen om de authenticatie-loop in C++ te implementeren. Dit biedt directe toegang tot de IOnlineSubsystem en de bijbehorende interfaces.

Hieronder vind je een complete, productierijpe C++-implementatie van een login- en achievement-handler:

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

Dit controller-ontwerp maakt gebruik van opeenvolgende callbacks. Dit zorgt ervoor dat de achievement-interface pas wordt aangesproken als de identity-interface met succes zowel de Epic Account ID als de Product User ID heeft opgelost.

Je DefaultEngine.ini-bestand configureren voor EOS

Blueprint login-nodes zullen niet initialiseren als de configuraties in je Config/DefaultEngine.ini-bestand onjuist zijn. De Online Subsystem EOS-plugin vereist specifieke parameters om te binden aan je game client.

Gebruik het volgende configuratiesjabloon om ervoor te zorgen dat je subsystem correct initialiseert:

[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

De configuratie van je DefaultEngine.ini-bestand fungeert als de brug tussen je gecompileerde game-binaries en de Epic Developer Portal. De parameters onder [OnlineSubsystemEOS] moeten exact overeenkomen met je productinstellingen.

Een veelvoorkomende bron van verwarring is het verschil tussen client credentials en sandbox ID's. De Client ID en Client Secret vertegenwoordigen de credentials van je game client, waarmee deze kan communiceren met de EOS-backend. De Sandbox ID vertegenwoordigt de specifieke omgeving (zoals Development, Staging of Live) waartoe je client toegang zoekt.

Als je game client probeert te authenticeren met een Sandbox ID die niet overeenkomt met de Client Credentials policy, wordt het authenticatieverzoek geweigerd. Daarnaast moet de bUseEpicConnect-vlag op true staan om ervoor te zorgen dat de Online Subsystem de EAID-naar-PUID-mapping automatisch achter de schermen afhandelt.

Overlay focus-mismatches en platformintegratie beheren

De EOS-plugin van Unreal leunt zwaar op de Epic Games Overlay om meldingen weer te geven, vriendenuitnodigingen te verwerken en OAuth-webauthenticaties uit te voeren. Wanneer je game client een login triggert met het credential-type AccountPortal, opent het besturingssysteem een browservenster of start het de overlay.

Deze omleiding verschuift de focus weg van het game-venster. Als je input-modes niet zijn ingesteld om focusverlies op te vangen, kan de game vastlopen of blijven toetsen hangen.

Het omgaan met door de overlay veroorzaakte input-problemen is een bekende hoofdpijn voor PC-developers. Overlay-injectie kan bijvoorbeeld conflicteren met raw input-drivers en ervoor zorgen dat toetsenbord- of muisstatussen bevriezen. Om te voorkomen dat deze bugs de spelerservaring verpesten, kun je onze analyse bekijken over The Marathon Input Issues Fix: Architecting PC Games to Survive Overlay Conflicts.

Bovendien worden initialisatiefouten tijdens het testen vaak veroorzaakt door verkeerd geconfigureerde socket-verbindingen of timeout-drempels in je lokale configuratie. Als je problemen met driver-timeouts tijdens het opstarten van een sessie aan het oplossen bent, bekijk dan onze handleiding over Uefn Session Launch Timeout Nightmares: Diagnosing Unreal Engine Network Drivers.

Cross-platform storefront-backends vereenvoudigen

Het handmatig configureren van storefront-subsystems, het schrijven van C++ delegate-chains en het omgaan met platformspecifieke overlay focus-problemen is uiterst tijdrovend. Dit moeten doen voor meerdere storefronts zoals Steam, EGS en consoles vermenigvuldigt je development-overhead.

Dit zelf bouwen vereist het opzetten van load balancers, database sharding en SSL-certificaatbeheer — al snel 4 tot 6 weken werk.

Met horizOn krijg je een uniform cross-platform backend dat deze storefront-API's abstraheert. In plaats van te moeten dealen met dubbele identity-tokens (EAID/PUID), Epic sandboxes of Steamworks-initialisatiecode, gebruik je een enkele API die user profiles, achievements, matchmaking en leaderboards afhandelt.

horizOn fungeert als een brug die achievements en speler-voortgang automatisch synchroniseert met de storefront van waaruit de gebruiker is gestart. Hierdoor kun jij je focussen op de game loop in plaats van op storefront-boilerplate. Dit betekent dat je spelers achievements kunnen unlocken, toegang hebben tot cloud saves en kunnen zoeken naar matches, ongeacht welk platform of welke launcher ze gebruiken, zonder dat jij één regel storefront-specifieke SDK-code hoeft te schrijven.

Moderne best practices voor Epic Online Services-integraties

1. Koppel asynchrone nodes nooit rechtstreeks: Wacht altijd tot de OnLoginComplete- en OnQueryAchievementsComplete-delegates zijn afgevuurd voordat je downstream-bewerkingen uitvoert, zoals het schrijven van stats of achievements.

2. Schakel verbose logging in tijdens development: Voeg de volgende regels toe aan je DefaultEngine.ini onder [Core.Log] om verborgen EOS-waarschuwingen te traceren:

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

3. Map achievements naar EOS in de Dev Portal: Zorg ervoor dat achievements die zijn gemaakt onder de Epic Games Store (EGS) expliciet zijn gemapt naar je Epic Online Services (EOS)-backend. Als ze niet gekoppeld zijn, zal de EOS SDK de achievement-ID niet herkennen.

4. Gebruik ExchangeCode in shipping builds: Tijdens lokale development is het Developer-logintype met een Dev Auth Tool handig, maar je moet het credentials-type omzetten naar ExchangeCode in shipping builds die worden gestart vanuit de Epic Games Launcher. Het gebruik van het door de launcher geleverde ExchangeCode-auth-type slaat de OAuth-redirection in de webbrowser over, waardoor de duur van de login-sequence wordt verkort van 8-12 seconden handmatige gebruikersinteractie tot een geautomatiseerde handshake van minder dan 500 ms.

Storefront-integraties stroomlijnen

Het oplossen van Epic Online Services login- en achievement-fouten in Unreal Engine komt neer op het begrijpen van de asynchrone pipeline en het perfect afgestemd houden van configuratieprofielen. Door de overgang tussen identity- en game service-interfaces te beheren, kunnen developers silent errors elimineren en een naadloze spelerservaring bieden.

Klaar om je multiplayer-backend te schalen? Probeer horizOn gratis of bekijk de API-docs.

---

Bron: Epic Games Store (Online Services AND Achievements)