Steamworks-dokumentation
Spilnotifikationer

Oversigt

Steam-spilnotifikationer er et system, som afleverer offline-notifikationer til brugere af spil, som har asynkront multiplayer-spil, som eksempelvis i skak.

Formålet med denne API er at give brugere besked om, at der kræves handling, for at en spilsession kan skride fremad. I eksemplet med skak opdateres spilsessionstilstanden efter hver spillers træk. Steam sender derefter notifikationer til brugerne baseret på spilsessionens tilstand for at give dem besked, når spillet venter på deres tur.

Spillets ansvarsområder

Et typisk offlinespil ville administrere en spilsession, opdatere hver brugers status med tilstande, som til gengæld vil sende en notifikation til brugerne, så de ved, at de skal starte spillet og udføre en handling. Efter lancering og udførelse af spilhandlinger forventes det, at spillet opdaterer spilsessionen igen med de opdaterede statistikker for alle brugere i sessionen.

Dette administrerer Steam

Steam vil sørge for at underrette brugere i en spilsession baseret på statistikkerne fra spillet og de specifikke indstillinger, som brugeren har valgt for spillet. Der vises en besked til brugeren i Steam-klienten og i webbrowseren, når handling er påkrævet i et spil.

Krav

Spilnotifikations-API'en stilles til rådighed gennem web-API-metoder og kræver en gyldig udgivernøgle. Kald fra web-API-metoden skal stamme fra en hosted server, som er adskilt fra spilklienten. Udgivernøglen må ikke udgives med anden spilklientkode.

Godkendelse og tredjepartskonti

For at kalde spilnotifikations-API'erne skal du først etablere identiteten af Steam-brugeren, som er logget ind i dit spil. Du kan gøre dette på en af to måder: Et klientspil kan generere en bekræftelsessessionsbillet og sende den tilbage til din server, og et webbaseret spil kan bekræfte brugeren ved at bruge OpenID. Instruktioner til, hvordan du gør dette, findes i Tilknytning af tredjepartskonti til Steam-konti. Det er vigtigt, at du ikke stoler på brugeridentitet i beskeder, som er sendt direkte fra spilklienten til din spilserver, da disse beskeder kan manipuleres.
For spil, som bruger tredjepartskonti, skal du bruge instruktionerne ovenfor, men cachelagre brugerens Steam-ID i dit system.

Spilnotifikations-API

Teknisk oversigt

Spilnotifikations-API'en er skrevet og eksponeret via web-API'er og kræver fire parametre sendes i hver metode:
  • appid (applikationens ID for dit spil)
  • format (formatet af resultatet. Vi anbefaler JSON som den returnerede værdi)
  • input_json (JSON-kodning af alle parametrerne kræves for en metode)
  • nøgle (din udgivernøgle, som skal sendes med hvert kald)
API'en returnerer en HTTP-statuskode på 200, når handlingen er gennemført, med detaljer i brødteksten (hvis relevant).

Konstante værdier

UserState

En strengværdi, som er defineret som en af de nedenstående:
  • waiting – Brugeren venter på andre spillere og blokerer ikke nogen handling. Der sendes ikke nogen notifikation til brugeren, fordi brugeren venter på, at noget sker.
  • ready – Brugeren er klar, og spilsessionen venter på et svar fra brugeren. En notifikation sendes til brugeren, indtil denne tilstand er blevet ryddet.
  • done – Spillet er afsluttet for denne bruger. Brugeren får besked om, at spillet er slut, men ingen handling er påkrævet.

Datastrukturer (JSON)

Alle datastrukturer er repræsenteret i JSON-format.

Variable

{ "key": "key_name", // streng "value": "value_of_key" // streng }

LocalizedText

{ "token": "value", // streng, som kortlægger en lokaliseret token "variables": [ // Array med "Variable" (ovenfor) ] }

UserStatus

{ "steamid": "76561197960265729", // uint64 "state": // En af "UserState"-konstanterne (beskrevet ovenfor), "title": // Et "LocalizedText"-objekt (beskrevet ovenfor), "message": // Et "LocalizedText"-objekt (beskrevet ovenfor) }

Session

{ "sessionid": "1", // uint64 "title": // Et "LocalizedText"-objekt (ovenfor), "time_created": "100000", // Unix Epoch-tid (tid siden 1. januar 1970). "time_updated": "200000", // Unix Epoch-tid (tid siden 1. januar 1970). // 64-bit værdi fra udvikleren, når sessionen oprettes, som gives til spillet, når det startes. // Dette gør det også muligt nemt at binde objektet til dit eget backend-objekt. Det bruges ikke internt i Steam. "context": "31415926", "user_status": [ // Array med "UserStatus"-objekter (beskrevet ovenfor) ] }

RequestedSession

{ "sessionid": "1", // uint64 "include_all_user_messages": "0" // bool }

Almindelige API'er, som er tilgængelige.

Se IGameNotificationsService for den komplette liste.

Lancering af specifikke spilsessioner

Brugere vil være i stand til at se alle deres aktive spilsessioner på deres fællesskabsprofilside i Steam. Sammen med spilstatussen er der en knap, som instruerer Steam til at starte spillet med specifikke startparametre til at definere spilsessionen. Når et spil startes på denne måde, vil en startparameter til "_sessionid" blive givet til spillet. Du kan modtage denne parameter ved at bruge ISteamApps::GetLaunchQueryParam.
Sådan her:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Et spil, som understøtter opstart direkte i et spil på denne måde, bør kalde denne grænseflade ved spilstart, afgøre, om sessionID-strengen er til stede, og om den er gyldig for den pågældende bruger, og derefter loade spillet direkte.

Lokalisering

Lokalisering leveres af spiludvikleren gennem et lokaliseringsværktøj, som er en del af applikationens konfiguration. Du er ansvarlig for opsætning af hvert sprogs oversættelse af hver streng, som indtastes i lokaliseringsværktøjet. Alle strenge, som ikke er oversat til en spillers sprog, vil blive gengivet på engelsk.
Spilnotifikation understøtter lokalisering til de følgende egenskaber:

Hver lokaliserede tekst består af to komponenter:

En token er en nøgle, som begynder med "#"-symbolet og repræsenterer en streng, som er lokaliseret på forskellige sprog gennem lokaliseringsværktøjet i din applikations konfiguration. En enkelt token kan indeholde flere variabeltilfælde, som kan erstattes ved kørsel baseret på konteksten i spillet, når teksten bliver genereret. For eksempel:
#InvitationText = "{{user}} has invited you to play a game of Chess."

I ovenstående eksempel indeholder den engelske oversættelse til #InvitationText en enkelt variabel kaldet "user". Når du ønsker at vise denne besked for en bruger, når "SteamUserName" inviterer brugeren til et spil, opdaterer du LocalizationText-objektet med de følgende egenskaber:
"message": { "token": "#InvitationText", "variables": [ { "key": "user", "value": "Michael" } ] }

Når spilleren ser sin status, vil spilleren se denne besked (på sit eget sprog): "Michael har inviteret dig til at spille et spil skak."
Lokaliseringstokens kan uploades i sektionen "Asynk-lokalisering" i fællesskabsfanen på indstillingssiden for din app i Steamworks.
Hvert sprog kan uploades individuelt i VDF-filer, som ser sådan her ud:
"lang" { "Language" "english" "Tokens" { "TheNameOfTheToken" "The localized text associated with the token" "TheNameOfAnotherToken" "The localized text associated with the second token" } }

Alternativt kan tokens for alle sprog uploades i en enkelt fil, som ser sådan her ud:
"lang" { "english" { "Tokens" { "TheNameOfTheToken" "The localized text associated with the token" "TheNameOfAnotherToken" "The localized text associated with the second token" } } "spanish" { "Tokens" { "TheNameOfTheToken" "El texto localizado asociado con el token" "TheNameOfAnotherToken" "El texto localizado asociado con el segundo token" } } }