Yleiskatsaus
Steamin peli-ilmoitukset on järjestelmä, jonka avulla toimitetaan käyttäjille offline-ilmoituksia peleistä, joissa pelataan asynkronista moninpeliä (esimerkiksi shakki).
Tämän ohjelmointirajapinnan tarkoituksena on ilmoittaa käyttäjille, että pelin edistyminen edellyttää toimenpiteitä. Peli-istunnon tila päivitetään kunkin pelaajan siirron jälkeen shakkipelin esimerkissä. Tämän jälkeen Steam lähettää ilmoituksia käyttäjille peli-istuntotilan perusteella, jotta he tietävät olevansa vuorossa.
Pelin tehtävät
Tyypillinen offline-peli hallitsee peli-istuntoa ja päivittää kullekin käyttäjälle tilan, joka lähettää puolestaan käyttäjälle ilmoituksen, että tämän on käynnistettävä peli ja toimittava. Käynnistyksen ja pelitoimintojen yhteydessä pelin pitäisi päivittää istunto uudelleen päivitetyillä pelaajatiedoilla.
Steamin tehtävät
Steam hallinnoi ilmoitusten lähettämistä pelaajille pelin ilmoittamien tilojen ja käyttäjän pelille valitsemien erityisasetusten perusteella. Ilmoitus näytetään Steam-sovelluksessa ja selaimessa käyttäjälle, kun pelissä edellytetään toimenpidettä.
Vaatimukset
Peli-ilmoitusten ohjelmointirajapinta tarjotaan verkko-ohjelmointirajapinnan metodeilla. Se edellyttää kelvollista julkaisijan avainta. Verkko-ohjelmointirajapinnan metodin kutsujen on oltava peräisin isännöidyltä palvelimelta, joka on erillinen pelisovelluksesta. Julkaisijan avainta ei saa lähettää pelitunnuksen mukana.
Varmennus ja kolmannen osapuolen tilit
Peli-ilmoitusten ohjelmointirajapintojen kutsuminen edellyttää, että selvität Steam-käyttäjän identiteetin. Sen voi tehdä kahdella tapaa. Pelin asiakasohjelma voi luoda todennusistuntolipun ja siirtää sen takaisin palvelimelle tai verkkopohjainen peli voi varmentaa käyttäjän OpenID-tunnistuksella. Ohjeet löytyvät täältä:
Kolmannen osapuolen tilien linkittäminen Steam-tileihin. Älä luota käyttäjän henkilöllisyyteen viesteissä, jotka on lähetetty suoraan pelisovelluksesta pelipalvelimellesi, sillä näitä viestejä voidaan peukaloida.
Noudata kolmannen osapuolen tilejä käyttävien pelien kohdalla edellä annettuja ohjeita, mutta tallenna käyttäjän SteamID järjestelmäsi välimuistiin.
Peli-ilmoitusten ohjelmointirajapinta
Tekniset tiedot
Peli-ilmoitusten ohjelmointirajapinta on kirjoitettu ja tarjotaan verkko-ohjelmointirajapinnan kautta, ja se edellyttää neljän parametrin määrittämistä kullekin metodille:
- appid (pelisi sovellustunnus)
- format (Tuloksen muoto. Suosittelemme paluuarvona json-muotoa)
- input_json (menetelmän edellyttämien muuttujien json-koodaus)
- key (julkaisijan avain, joka määritetään jokaisessa kutsussa)
Ohjelmointirajapinta palauttaa onnistumisesta HTTP-tilakoodin 200, ja viestin teksti sisältää (tarvittaessa) tarkemmat tiedot.
Vakioarvot
UserState
Merkkijonon arvo, joka määritellään yhdeksi seuraavista:
- waiting – Käyttäjä odottaa muita pelaajia eikä estä muita toimintoja. Käyttäjälle ei lähetetä ilmoitusta, koska hän odottaa, että jotakin tapahtuu.
- ready – Käyttäjä on valmis – peli-istunto odottaa vastausta käyttäjältä. Käyttäjälle lähetetään ilmoitus, kunnes tämä tila on poistettu.
- done – Peli on pelattu kyseisen pelaajan osalta loppuun. Käyttäjälle ilmoitetaan, että peli on päättynyt, mutta mitään toimia ei tarvita.
Tietorakenteet (JSON)
Kaikki tietorakenteet esitetään JSON-muodossa.
Variable
{
"key": "key_name", // merkkijono
"value": "value_of_key" // merkkijono
}
LocalizedText
{
"token": "value", // merkkijono, joka kuvaa lokalisointitunnistetta
"variables":
[
"
// muuttujataulukko (yllä)
]
}
UserStatus
{
"steamid": "76561197960265729", // uint64
"state": // yksi (ylläkuvatuista) UserState-vakioista
"title": // LocalizedText-objekti (kuvattu yllä)
"message": // LocalizedText-objekti (kuvattu yllä)
}
Session
{
"sessionid": "1", // uint64
"title": // LocalizedText-objekti (yllä)
"time_created": "100000", // Unix-aika (1.1.1970 alkaen)
"time_updated": "200000", // Unix-aika (1.1.1970 alkaen)
// 64-bittinen arvo, jonka kehittäjä tarjoaa, kun istunto on luotu, ja joka siirretään peliin, kun se käynnistetään.
// Näin yhdistät helposti istunto-objektin omaan palvelinpuolen objektiin. Steam ei käytä sitä sisäisesti.
"context": "31415926",
"user_status":
[
// UserStatus-objektin taulukko (kuvattu yllä)
]
}
RequestedSession
{
"sessionid": "1", // uint64
"include_all_user_messages": "0" // bool
}
Yleisiä saatavilla olevia ohjelmointirajapintoja
Koko lista on kohdassa
IGameNotificationsService.
Tiettyjen peli-istuntojen käynnistäminen
Käyttäjät voivat tarkastella kaikkia aktiivisia peli-istuntojaan yhteisöprofiilisivullaan Steamissä. Pelin tilan lisäksi sivulla näkyy painike, jolla voidaan pyytää Steamia käynnistämään peli erityisillä käynnistysmuuttujilla peli-istunnon määrittelemiseksi. Kun peli käynnistetään tällä tavalla, pelille annetaan parametri "_sessionid". Saat tämän parametrin käyttämällä
ISteamApps::GetLaunchQueryParam-jäsenfuntiota
seuraavasti:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Pelin, joka tukee pelin käynnistämistä suoraan tällä tavalla, pitäisi kutsua käyttöliittymää ja määritellä, esiintyykö istuntotunnuksen merkkijono ja onko se voimassa sisäänkirjautuneelle käyttäjälle, ja ladata peli suoraan.
Lokalisointi
Pelikehittäjä tarjoaa lokalisoinnin sovellusmäärityksiin kuuluvalla lokalisointityökalulla. Olet vastuussa kunkin kielen jokaisen käännöksen määrittämisestä lokalisointityökalussa. Merkkijonot, joita ei ole käännetty pelaajan kielelle, esitetään englanniksi.
Peli-ilmoitukset tukevat lokalisointia seuraavien ominaisuuksien osalta:
Kukin
lokalisoitu teksti koostuu kahdesta komponentista:
Tunniste on avain, joka alkaa #-symbolilla ja kuvaa merkkijonoa, joka on lokalisoitu eri kielille sovellusmääritysten lokalisointityökalulla. Yksittäinen tunniste voi sisältää useita muuttujan esiintymiä, jotka voidaan korvata suoritusaikana pelin kontekstin perusteella, kun tekstiä luodaan. Esimerkki:
#InvitationText = "{{user}} has invited you to play a game of Chess."Edellä olevassa esimerkissä englanninkielinen käännös tunnisteelle #InvitationText sisältää yhden muuttujan nimeltä käyttäjä. Jos haluat renderöidä tämän tekstimuotoisen viestin käyttäjälle, kun "SteamUserName" kutsuu hänet peliin, päivitä LocalizationText-objekti seuraavilla ominaisuuksilla:
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "Michael" }
]
}
Kun pelaaja katsoo omaa tilaansa, hän näkee seuraavan viestin (omalla kielellään): "Michael on kutsunut sinut pelaamaan Chess-peliä."
Lokalisointimerkit voi ladata sovelluksellesi Steamworks-asetussivulta, Yhteisö-välilehden asynkronisen lokalisoinnin kohdasta.
Kunkin kielen voi ladata erikseen VDF-tiedostoina, jotka näyttävät seuraavilta:
"lang"
{
"Language" "english"
"Tokens"
{
"TheNameOfTheToken" "The localized text associated with the token"
"TheNameOfAnotherToken" "The localized text associated with the second token"
}
}
Vaihtoehtoisesti kaikkien kielten tunnisteet voidaan lähettää yhdessä tiedostossa, joka näyttää tältä:
"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"
}
}
}
