DokumentationAnalyticsGuide för direktuppspelande medietjänster

Spåra spelarlägen

Senast uppdaterad: 29 maj 2026

Skapat för:

  • Developer

Med spelarlägeshändelser spåras hur tittarna interagerar med spelarkontroller under en session. De är valfria och behövs inte för implementeringar av mediespårning. De fem spårbara lägena är: fullscreen, mute, closedCaptioning, pictureInPicture och inFocus.

Händelser för spelartillstånd är användbara för att förstå tillgänglighetsfunktioner, till exempel hur ofta visningsprogram aktiverar undertextning eller stänger av ljudet. De visar också visningsbeteendemönster som helskärmsvisning och infogad visning och bild-i-bild-multitasking.

Spelarhändelser

Spelarhändelse
Åtgärd
Spelaren försätts i ett läge
Samtalsläge - start
Spelaren avslutar ett läge
Samtalsläge - slut

Standard och anpassade lägen

Fem standardspelarlägen är tillgängliga och du kan lägga till egna anpassade lägen.

Standardlägesnamn
Konstanten Media SDK
API-namn för mediesamling
Helskärm
ADB.Media.PlayerState.Fullscreen
fullScreen
Undertexter
ADB.Media.PlayerState.ClosedCaptioning
closedCaptioning
Ljud
ADB.Media.PlayerState.Mute
mute
Bild-i-bild
ADB.Media.PlayerState.PictureInPicture
pictureInPicture
I fokus
ADB.Media.PlayerState.InFocus
inFocus

Mer information om den fullständiga variabelreferensen, inklusive XDM-sökvägar och metriska definitioner, finns i Player-lägesvariabler.

Anpassade lägen: Du kan skapa anpassade lägen om du vill hämta ytterligare spelarbeteenden som är specifika för ditt program. Se Referens för medie-API: createStateObject ​ om du vill ha mer information om hur du skapar anpassade lägesobjekt.

Implementeringssteg

  1. Anropa Lägesstart när spelaren går in i något av de fem spårbara lägena. Flera lägen kan vara aktiva samtidigt och flera lägen kan startas i samma händelseanrop.
  2. Anropa Lägesslut när spelaren avslutar ett läge. Flera lägen kan avslutas i samma händelseanrop och lägen kan startas och avslutas tillsammans i ett enda anrop.

Riktlinjer

  • En videosession är begränsad till tio spelarlägen.
  • Alla kombinationer av lägen är tillåtna.
  • Om flera spelarlägen skickas behålls endast de första 10 och vidarebefordras nedströms till medieservern.
  • Det maximala antalet 10 lägen gäller för alla lägen, oavsett om de är öppna eller stängda.
  • Ett läge kan starta och avslutas flera gånger och räknas som ett enda läge. closedCaptioning kan till exempel startas och stoppas fem gånger men räknas som ett läge.
  • Spelarläget beräknas för alla uppspelningslägen (ingen delning).
  • Spelartillstånd hämtas för varje enskild uppspelningssession. Spelarläget beräknas inte för alla uppspelningar.
  • Kunskap om programstatus upprätthålls inte när ett tillstånd har stoppats. När ett läge har avslutats måste läget startas igen för att fortsätta spåra.

Uppdatera flera lägen samtidigt

På XDM-baserade plattformar kan flera lägesändringar grupperas i ett enda statesUpdate-anrop med hjälp av arrayer i statesStart och statesEnd. På mobila SDK:er kräver varje lägesändring ett separat anrop.

I följande exempel startas ljud av och bild-i-bild tillsammans och sedan övergången till helskärm.

Rekommenderade implementeringstyper

SDK för webben
code language-javascript 
// t0 — start mute and picture-in-picture together
alloy("sendEvent", {
  xdm: {
    eventType: "media.statesUpdate",
    mediaCollection: {
      statesStart: [{ name: "mute" }, { name: "pictureInPicture" }],
      sessionID: "{sid}",
      playhead: 0
    }
  }
});

// t1 — end mute and picture-in-picture; start full screen
alloy("sendEvent", {
  xdm: {
    eventType: "media.statesUpdate",
    mediaCollection: {
      statesEnd: [{ name: "mute" }, { name: "pictureInPicture" }],
      statesStart: [{ name: "fullscreen" }],
      sessionID: "{sid}",
      playhead: 0
    }
  }
});

// t2 — end full screen
alloy("sendEvent", {
  xdm: {
    eventType: "media.statesUpdate",
    mediaCollection: {
      statesEnd: [{ name: "fullscreen" }],
      sessionID: "{sid}",
      playhead: 0
    }
  }
});
iOS

Mobile SDK saknar stöd för gruppbearbetning — skicka ett separat samtal för varje lägesändring.

code language-swift 
// t0 — start mute and picture-in-picture
let muteState = Media.createStateObjectWith(stateName: MediaConstants.PlayerState.MUTE)
let pipState = Media.createStateObjectWith(stateName: MediaConstants.PlayerState.PICTURE_IN_PICTURE)
tracker.trackEvent(event: MediaEvent.StateStart, info: muteState, metadata: nil)
tracker.trackEvent(event: MediaEvent.StateStart, info: pipState, metadata: nil)

// t1 — end mute and picture-in-picture; start full screen
tracker.trackEvent(event: MediaEvent.StateEnd, info: muteState, metadata: nil)
tracker.trackEvent(event: MediaEvent.StateEnd, info: pipState, metadata: nil)
let fullscreenState = Media.createStateObjectWith(stateName: MediaConstants.PlayerState.FULLSCREEN)
tracker.trackEvent(event: MediaEvent.StateStart, info: fullscreenState, metadata: nil)

// t2 — end full screen
tracker.trackEvent(event: MediaEvent.StateEnd, info: fullscreenState, metadata: nil)
Android

Mobile SDK saknar stöd för gruppbearbetning — skicka ett separat samtal för varje lägesändring.

code language-kotlin 
// t0 — start mute and picture-in-picture
val muteState = Media.createStateObject(MediaConstants.PlayerState.MUTE)
val pipState = Media.createStateObject(MediaConstants.PlayerState.PICTURE_IN_PICTURE)
tracker.trackEvent(Media.Event.StateStart, muteState, null)
tracker.trackEvent(Media.Event.StateStart, pipState, null)

// t1 — end mute and picture-in-picture; start full screen
tracker.trackEvent(Media.Event.StateEnd, muteState, null)
tracker.trackEvent(Media.Event.StateEnd, pipState, null)
val fullscreenState = Media.createStateObject(MediaConstants.PlayerState.FULLSCREEN)
tracker.trackEvent(Media.Event.StateStart, fullscreenState, null)

// t2 — end full screen
tracker.trackEvent(Media.Event.StateEnd, fullscreenState, null)
Roku
code language-brightscript 
' t0 — start mute and picture-in-picture together
m.aepSdk.sendMediaEvent({
    "xdm": {
        "eventType": "media.statesUpdate",
        "mediaCollection": {
            "statesStart": [{"name": "mute"}, {"name": "pictureInPicture"}],
            "playhead": 0
        }
    }
})

' t1 — end mute and picture-in-picture; start full screen
m.aepSdk.sendMediaEvent({
    "xdm": {
        "eventType": "media.statesUpdate",
        "mediaCollection": {
            "statesEnd": [{"name": "mute"}, {"name": "pictureInPicture"}],
            "statesStart": [{"name": "fullscreen"}],
            "playhead": 0
        }
    }
})

' t2 — end full screen
m.aepSdk.sendMediaEvent({
    "xdm": {
        "eventType": "media.statesUpdate",
        "mediaCollection": {
            "statesEnd": [{"name": "fullscreen"}],
            "playhead": 0
        }
    }
})
Media Edge API
code language-sh 
# t0 — start mute and picture-in-picture together
curl -X POST "https://edge.adobedc.net/ee/va/v1/statesUpdate?configId={datastreamID}" \
--header 'Content-Type: application/json' \
--data '{
  "events": [{
    "xdm": {
      "eventType": "media.statesUpdate",
      "mediaCollection": {
        "statesStart": [{"name": "mute"}, {"name": "pictureInPicture"}],
        "sessionID": "{sid}",
        "playhead": 0
      },
      "timestamp": "YYYY-01-01T00:00:00+00:00"
    }
  }]
}'

# t1 — end mute and picture-in-picture; start full screen
curl -X POST "https://edge.adobedc.net/ee/va/v1/statesUpdate?configId={datastreamID}" \
--header 'Content-Type: application/json' \
--data '{
  "events": [{
    "xdm": {
      "eventType": "media.statesUpdate",
      "mediaCollection": {
        "statesEnd": [{"name": "mute"}, {"name": "pictureInPicture"}],
        "statesStart": [{"name": "fullscreen"}],
        "sessionID": "{sid}",
        "playhead": 0
      },
      "timestamp": "YYYY-01-01T00:01:00+00:00"
    }
  }]
}'

# t2 — end full screen
curl -X POST "https://edge.adobedc.net/ee/va/v1/statesUpdate?configId={datastreamID}" \
--header 'Content-Type: application/json' \
--data '{
  "events": [{
    "xdm": {
      "eventType": "media.statesUpdate",
      "mediaCollection": {
        "statesEnd": [{"name": "fullscreen"}],
        "sessionID": "{sid}",
        "playhead": 0
      },
      "timestamp": "YYYY-01-01T00:02:00+00:00"
    }
  }]
}'

Äldre implementeringstyper (endast analys)

Media SDK JS 3.x

Flera lägesändringar kräver separata anrop.

code language-javascript 
// t0 — start mute and picture-in-picture
var muteState = ADB.Media.createStateObject(ADB.Media.PlayerState.Mute);
var pipState = ADB.Media.createStateObject(ADB.Media.PlayerState.PictureInPicture);
tracker.trackPlayerStateStart(muteState);
tracker.trackPlayerStateStart(pipState);

// t1 — end mute and picture-in-picture; start full screen
tracker.trackPlayerStateEnd(muteState);
tracker.trackPlayerStateEnd(pipState);
var fullscreenState = ADB.Media.createStateObject(ADB.Media.PlayerState.FullScreen);
tracker.trackPlayerStateStart(fullscreenState);

// t2 — end full screen
tracker.trackPlayerStateEnd(fullscreenState);
Chromecast

Flera lägesändringar kräver separata anrop.

code language-javascript 
// t0 — start mute and picture-in-picture
var muteState = ADBMobile.media.createStateObject(ADBMobile.media.PlayerState.Mute);
var pipState = ADBMobile.media.createStateObject(ADBMobile.media.PlayerState.PictureInPicture);
ADBMobile.media.trackEvent(ADBMobile.media.Event.StateStart, muteState, null);
ADBMobile.media.trackEvent(ADBMobile.media.Event.StateStart, pipState, null);

// t1 — end mute and picture-in-picture; start full screen
ADBMobile.media.trackEvent(ADBMobile.media.Event.StateEnd, muteState, null);
ADBMobile.media.trackEvent(ADBMobile.media.Event.StateEnd, pipState, null);
var fullscreenState = ADBMobile.media.createStateObject(ADBMobile.media.PlayerState.FullScreen);
ADBMobile.media.trackEvent(ADBMobile.media.Event.StateStart, fullscreenState, null);

// t2 — end full screen
ADBMobile.media.trackEvent(ADBMobile.media.Event.StateEnd, fullscreenState, null);
Media Collection API
code language-json 
// t0 — start mute and picture-in-picture together
{
  "eventType": "statesUpdate",
  "params": {
    "statesStart": [
      { "media.state.name": "mute" },
      { "media.state.name": "pictureInPicture" }
    ]
  },
  "playerTime": { "playhead": 0, "ts": 1569999130627 }
}

// t1 — end mute and picture-in-picture; start full screen
{
  "eventType": "statesUpdate",
  "params": {
    "statesEnd": [
      { "media.state.name": "mute" },
      { "media.state.name": "pictureInPicture" }
    ],
    "statesStart": [
      { "media.state.name": "fullScreen" }
    ]
  },
  "playerTime": { "playhead": 0, "ts": 1569999230627 }
}

// t2 — end full screen
{
  "eventType": "statesUpdate",
  "params": {
    "statesEnd": [{ "media.state.name": "fullScreen" }]
  },
  "playerTime": { "playhead": 0, "ts": 1569999330627 }
}

Lång paus

När en videosession har en paus som är längre än 30 minuter krävs en ny session för API:t. Generera ett nytt sessions-ID och bevara alla aktiva lägen så att de kan återställas med stateStart händelser direkt efter det nya sessionStart-anropet.

sessionStart → stateStart (fullscreen) → stateStart (mute) → pauseStart → (pings for 30 minutes) → sessionEnd

När sessionEnd har skickats startar du en ny session och skickar omedelbart om de aktiva lägena:

sessionStart → stateStart (fullscreen) → stateStart (mute) → ... other API events

Lägesmått

Tre mätvärden beräknas för varje spårat läge och skickas till Adobe Analytics via ett mediastängningssamtal:

Mått
Kontextdatanyckel
Beskrivning
Tillståndsuppsättning
a.media.states.[state.name].set = true
true om läget ställdes in minst en gång under uppspelningen
Antal lägen
a.media.states.[state.name].count = 4
Antal gånger som läget inträffade under uppspelningen
Lägestid
a.media.states.[state.name].time = 240
Total tid (sekunder) som har använts i läget under uppspelningen
recommendation-more-help
media-analytics-help