Referência da API do SDK do JavaScript javascript-sdk-api-reference
Referência da API api-reference
Essas funções iniciam solicitações de interação com um MVPD. Todas as chamadas são assíncronas; você deve implementar retornos de chamada para lidar com as respostas:
setRequestor (inRequestorID, pontos de extremidade, opções) setrequestor(inRequestorID,endpoints,options)
Descrição: Identifica o site do qual as solicitações se originam. Você deve fazer essa chamada antes de qualquer outra chamada de API em uma sessão de comunicação.
Parâmetros:
-
inRequestorID - O identificador exclusivo que o Adobe atribuiu ao site de origem durante o registro.
-
endpoints - Este parâmetro é opcional. Pode ser um dos seguintes valores:
- Uma matriz que permite especificar endpoints para serviços de autenticação e autorização fornecidos pelo Adobe (instâncias diferentes podem ser usadas para fins de depuração). Caso vários URLs sejam fornecidos, a lista MVPD é composta pelos endpoints de todos os provedores de serviços. Cada MVPD está associado ao provedor de serviços mais rápido; ou seja, o provedor que respondeu primeiro e que oferece suporte a esse MVPD. Por padrão (se nenhum valor for especificado), o provedor de serviços da Adobe é usado (http://sp.auth.adobe.com/).
Exemplo:
setRequestor("IFC", ["http://sp.auth-dev.adobe.com/adobe-services"])
-
opções - Um objeto JSON que contém o valor da ID do aplicativo, o valor da ID do visitante e as configurações sem atualização (logout em segundo plano) e as configurações de MVPD (iFrame). Todos os valores são opcionais.
- Se especificado, o Experience Cloud visitorID será relatado em todas as chamadas de rede executadas pela biblioteca. O valor pode ser usado posteriormente para relatórios de análise avançada.
- Se o identificador exclusivo do aplicativo for especificado -
applicationId
- o valor será adicionado a todas as chamadas subsequentes feitas pelo aplicativo como parte do cabeçalho HTTP X-Device-Info. Este valor pode ser obtido posteriormente dos relatórios ESM usando a consulta adequada.
Observação: todas as chaves JSON diferenciam maiúsculas de minúsculas.
Exemplo:
setRequestor("IFC", {
"visitorID": "THE_ECID_VALUE",
"applicationId": "APP_ID_VALUE"
})
- O Programador pode substituir as configurações do MVPD definidas na Autenticação do Adobe Pass, especificando se um iFrame é necessário ou não para logon (chave iFrameRequired) e as dimensões do iFrame (chaves iFrameWidth e iFrameHeight). O objeto JSON tem o seguinte modelo:
{
"visitorID": <string>,
"backgroundLogin": <boolean>,
"backgroundLogout": <boolean>,
"mvpdConfig":{
"MVPD_ID_1":{
"iFrameRequired": <boolean>,
"iFrameWidth": <integer>,
"iFrameHeight": <integer>
},
...
"MVPD_ID_N":{
"iFrameRequired": <boolean>,
"iFrameWidth": <integer>,
"iFrameHeight": <integer>
}
}
}
Todas as chaves de nível superior no modelo acima são opcionais e têm valores padrão (backgroundLogin, backgroundLogut são falsos por padrão e mvpdConfig é nulo - o que significa que nenhuma configuração MVPD é substituída).
- Observação: a especificação de valores/tipos inválidos para os parâmetros acima resultará em um comportamento indefinido.
Este é um exemplo de configuração para o seguinte cenário: ativar o logon e o logout sem atualização, alterar MVPD1 para logon de redirecionamento de página completa (não iFrame) e MVPD2 para logon de iFrame com width=500 e height=300:
{
"backgroundLogin": true,
"backgroundLogout": true,
"mvpdConfig":{
"MVPD1":{
"iFrameRequired": false
},
"MVPD2":{
"iFrameRequired": true,
"iFrameWidth": 500,
"iFrameHeight": 300
}
}
}
Retornos de chamada disparados: setConfig()
getAuthorization(inResourceID, redirect_url) getauthorization(inresourceid,redirect_url)
Descrição: solicita autorização para o recurso especificado. Cada vez que um cliente tentar acessar um recurso autorizável, chame essa função para obter um token de autorização de curta duração do Ativador de acesso. As IDs de recursos são acordadas com o MVPD que fornece autorização.
Usa o token de autenticação em cache para o cliente atual. Se esse token não for encontrado, o iniciará o processo de autenticação primeiro e, em seguida, continuará com a autorização.
Parâmetros:
inResourceID
- A identificação do recurso para o qual o usuário solicita autorização.redirect_url
- Opcionalmente, forneça uma URL de redirecionamento, para que o processo de autorização do MVPD retorne o usuário a essa página, em vez da página a partir da qual a autorização foi iniciada.
Retornos de chamada disparados: setToken() com êxito, tokenRequestFailed com falha
getAuthentication(redirect_url) getauthentication(redirect_url
Descrição: solicita autenticação para o cliente atual. Normalmente chamado em resposta a um clique em um botão de Logon. Procura um token de autenticação em cache para o cliente atual. Se esse token não for encontrado, o iniciará o processo de autenticação. Isso chama a caixa de diálogo de seleção de provedor padrão ou personalizada e, em seguida, usa o provedor selecionado para redirecionar para a interface de logon do MVPD.
Quando bem-sucedido, o cria e armazena um token de autenticação para o usuário. Se a autenticação falhar, o provedor retornará uma mensagem de erro apropriada ao retorno de chamada setAuthenticationStatus().
Parâmetros:
- redirect_url - Opcionalmente, forneça um URL de redirecionamento, para que o processo de autenticação do MVPD retorne o usuário para essa página, em vez da página a partir da qual a autenticação foi iniciada.
Retornos de chamada disparados: setAuthenticationStatus(), displayProviderDialog(), sendTrackingData()
checkAuthN checkauthn
Descrição: verifica o status de autenticação atual do cliente atual. Não associado a nenhuma interface do usuário.
Retornos de chamada disparados: setAuthenticationStatus()
checkAuthorization(inResourceID) checkauthorization(inresourceid)
Descrição: Este método é usado pelo aplicativo para verificar o status de autorização do cliente atual e do recurso fornecido. Ela é iniciada verificando o status de autenticação primeiro. Se não for autenticado, o retorno de chamada tokenRequestFailed() será acionado e o método será encerrado. Se o usuário estiver autenticado, ele também acionará o fluxo de autorização. Consulte detalhes sobre o [getAuthorization()] (#getAuthZ method.
Parâmetros:
inResourceID
- A identificação do recurso para o qual o usuário solicita autorização.
Retornos de chamada disparados:
setToken(), tokenRequestFailed(), sendTrackingData(), setAuthenticationStatus()
checkPreauthorizedResources(resources) checkPreauthorizedResources(resources)
Descrição: Solicita o status de autorização de "comprovação" para uma lista de
recursos.
Parâmetros:
- recursos: o parâmetro de recursos é uma matriz de recursos cuja autorização deve ser verificada. Cada elemento na lista deve ser uma string que representa a ID do recurso. A ID do recurso está sujeita às mesmas limitações que a ID do recurso na chamada
getAuthorization()
, ou seja, é um valor acordado estabelecido entre o Programador e o MVPD, ou um fragmento de RSS de mídia.
checkPreauthorizedResources(resources-cache=true) checkPreauthorizedResources(resources-cache=true)
Esta variante de API está disponível a partir do JS SDK versão 4.0
Parâmetros:
-
recursos: o parâmetro de recursos é uma matriz de recursos cuja autorização deve ser verificada. Cada elemento na lista deve ser uma string que representa a ID do recurso. A ID do recurso está sujeita às mesmas limitações que a ID do recurso na chamada
getAuthorization()
, ou seja, é um valor acordado estabelecido entre o Programador e o MVPD, ou um fragmento de RSS de mídia. -
cache: se o cache interno deve ser usado ao verificar recursos pré-autorizados. Este é um parâmetro opcional, padronizando como true. Se verdadeiro, o comportamento é idêntico à API acima, o que significa que as chamadas subsequentes a essa função usarão um cache interno para resolver o recurso pré-autorizado. Passar false para esse parâmetro desabilitará o cache interno, resultando em uma chamada de servidor sempre que a API checkPreauthorizedResources for chamada.
Retornos de chamada disparados: preauthorizedResources()
getMetadata(Key) getMetadata
Descrição: Recupera informações expostas como metadados pela biblioteca do Ativador de Acesso.
Há dois tipos de metadados:
- Estático (TTL de token de autenticação, TTL de token de autorização e ID de dispositivo)
- Metadados do Usuário (Isso inclui informações específicas do usuário que são passadas do MVPD para o dispositivo do usuário durante os fluxos de Autenticação e/ou Autorização)
Mais Informações: Metadados de Usuário
Parâmetros:
-
chave: uma ID que especifica os metadados solicitados:
-
Se a chave for
"TTL_AUTHN",
, a consulta será feita para obter o tempo de expiração do token de autenticação. -
Se a chave for
"TTL_AUTHZ"
e params for uma matriz contendo a ID do recurso como uma cadeia de caracteres, a consulta será feita para obter a hora de expiração do token de autorização associado ao recurso especificado. -
Se a chave for
"DEVICEID"
, será feita a consulta para obter a ID do dispositivo atual. Observe que esse recurso está desativado por padrão e os programadores devem entrar em contato com o Adobe para obter informações sobre ativação e taxas. -
Se a chave for da seguinte lista de tipos de metadados de usuário, um objeto JSON contendo os metadados de usuário correspondentes será enviado para a função de retorno de chamada
setMetadataStatus()
: -
"zip"
- CEP -
"encryptedZip"
- CEP criptografado -
"householdID"
- Identificador da família. No caso de um MVPD não suportar subcontas, isso será idêntico a userID. -
"maxRating"
- Classificação máxima dos pais para o usuário -
"userID"
- O identificador do usuário. No caso em que um MVPD oferece suporte a subcontas e o usuário não é a conta principal, a ID do usuário será diferente da ID da família. -
"channelID"
- A lista de canais que o usuário tem direito a visualizar -
"is_hoh"
- Sinalizador que identifica se um usuário é chefe de família -
"encryptedZip"
- CEP criptografado -
"typeID"
- Sinalizador que identifica se a conta do usuário é conta primária/secundária -
"primaryOID"
- Identificador da família -
"postalCode"
- Semelhante ao CEP -
"acctID"
- ID da conta -
"acctParentID"
- ID da conta principal
Observação: os Metadados de Usuário reais disponíveis para um Programador dependem do que um MVPD disponibiliza. Consulte Metadados do Usuário para obter a lista atual de Metadados do Usuário disponíveis.
-
Por exemplo:
// Assume that a reference to the AccessEnabler has been previously
// obtained and stored in the "ae" variable
ae.setRequestor("SITE");
ae.checkAuthentication();
function setAuthenticationStatus(status, reason) {
if (status == 1) {
//user is authenticated, request metadata
ae.getMetadata("zip");
ae.getMetadata("maxRating");
} else {
...
}
}
Retornos de chamada disparados: setMetadataStatus()
setSelectedProvider(providerid) setSelectedProvider
Descrição: Chame esta função quando o usuário tiver selecionado um MVPD na sua interface de seleção de provedor para enviar a seleção de provedor para o Ativador de Acesso ou chame esta função com um parâmetro nulo caso o usuário tenha descartado sua interface de seleção de provedor sem selecionar um provedor.
Retornos de chamada
acionado: setAuthenticationStatus(), sendTrackingData()
getSelectedProvider() getSelectedProvider
Descrição: Recupera os resultados da seleção do cliente na caixa de diálogo de seleção de provedor. Isso pode ser usado a qualquer momento após a verificação de autenticação inicial.
Esta função é assíncrona e retorna seu resultado à função de retorno de chamada selectedProvider()
.
- MVPD O MVPD selecionado no momento ou nulo se nenhum MVPD foi selecionado.
- AE_State O resultado da autenticação para o cliente atual de "Novo Usuário", "Usuário Não Autenticado" ou "Usuário Autenticado"
Retornos de chamada disparados: seletedProvider()
logout logout
Descrição: faz logoff do cliente atual, limpando todas as informações de autenticação e autorização desse usuário. Exclui todos os tokens authN e authZ do sistema do cliente.
Retornos de chamada disparados: setAuthenticationStatus()
Definição de retorno de chamada calllback-definitions
Você deve implementar esses retornos de chamada para lidar com as respostas às suas chamadas de solicitação assíncronas:
titlementLoaded() entitlementLoaded
Descrição: acionado quando o Ativador de Acesso conclui a inicialização e está pronto para receber solicitações. Implemente essa chamada de retorno para saber quando você pode iniciar a comunicação com a API do Access Enabler.
setConfig(configXML) setconfig(configXML)
Descrição: Implemente esta chamada de retorno para receber as informações de configuração e a lista MVPD.
Parâmetros:
- configXML: objeto xml que contém a configuração do SOLICITANTE atual, incluindo a lista MVPD.
Acionado por: setRequestor()
displayProviderDialog(provedores) displayproviderdialog(providers)
Descrição: Implemente esta chamada de retorno para invocar sua própria interface personalizada de seleção de provedor. Sua caixa de diálogo deve usar o nome de exibição (e o logotipo opcional) para fornecer as opções do cliente. Quando o cliente tiver escolhido e descartado a caixa de diálogo, envie a ID associada do provedor escolhido na chamada para setSelectedProvider().
Parâmetros:
- provedores - Uma matriz de Objetos que representa os MVPDs solicitados:
var mvpd = {
ID: "someprov",
displayName: "Some Provider",
logoURL: "http://www.someprov.com/images/logo.jpg"
}
Acionado por: getAuthentication(), getAuthorization()
createIFrame(inWidth, inHeight) createIFrame(inWidth,inHeight)
Descrição: implemente esse retorno de chamada se o usuário tiver selecionado um MVPD que exija um iFrame no qual ele possa exibir sua interface da página de logon de autenticação.
Acionado por: setSelectedProvider()
setAuthenticationStatus(isAuthenticated, errorCode) set-authn-status-isauthn-error
Descrição: Implemente esta chamada de retorno para receber o status de autenticação (1=autenticado ou 0=não autenticado) e uma mensagem de erro descritiva se ocorrer algum erro ao tentar determinar o status de autenticação (cadeia vazia na conclusão bem-sucedida da verificação).
Parâmetros:
- isAuthenticated - Fornece o status de autenticação: 1 (autenticado) ou 0 (não autenticado).
- errorCode - qualquer erro que ocorra ao determinar o status de autenticação. Uma cadeia de caracteres vazia, se nenhuma.
Acionado por: checkAuthentication(), getAuthentication(), checkAuthorization()
sendTrackingData(trackingEventType, trackingData) sendTrackingData(trackingEventType,trackingData)
Descrição: implemente essa chamada de retorno para receber dados de rastreamento quando eventos específicos ocorrerem. Você pode usar isso, por exemplo, para rastrear quantos usuários fizeram logon com as mesmas credenciais. O rastreamento não está configurável no momento. Com a Autenticação Adobe Pass 1.6, o sendTrackingData()
também relata informações sobre o dispositivo, o cliente do Ativador de Acesso e o tipo de sistema operacional. O retorno de chamada sendTrackingData()
permanece compatível com versões anteriores.
-
Valores possíveis para o tipo de dispositivo:
- computador
- tablet
- dispositivo móvel
- gameconsole
- desconhecido
-
Valores possíveis para o tipo de cliente do Access Enabler:
- html5
- ios
- android
Passa o tipo de evento e uma matriz de informações associadas. Os tipos de evento são:
Acionado por: checkAuthentication(), getAuthentication(), checkAuthorization(), getAuthorization()
setToken(inRequestedResourceID, inToken) setToken(inRequestedResourceID,inToken)
Descrição: Implemente esta chamada de retorno para receber o token de mídia de vida curta (inToken) e a ID do recurso (inRequestedResourceID) para o qual foi feita uma solicitação de autorização ou uma solicitação de autorização de verificação e concluída com êxito.
Acionado por: checkAuthorization(), getAuthorization()
tokenRequestFailed(inRequestedResourceID, inRequestErrorCode, inRequestDetailedErrorMessage) token-request-failed-error-msg
Descrição: Implemente esta chamada de retorno para ser sinalizada quando uma autorização ou uma solicitação de autorização de verificação falhar. Pode, opcionalmente, ser usado por um MVPD para fornecer uma mensagem personalizada a ser exibida pelo Programador.
Parâmetros:
- inRequestedResourceID - Uma cadeia de caracteres que fornece a ID de Recurso que foi usada na solicitação de autorização.
- inRequestErrorCode - Uma cadeia de caracteres que exibe o código de erro de Autenticação do Adobe Pass, indicando o motivo da falha; os valores possíveis são "Erro de Usuário Não Autenticado" e "Erro de Usuário Não Autorizado"; para obter mais detalhes, consulte "Códigos de erro de retorno de chamada" abaixo.
- inRequestDetailedErrorMessage - Uma cadeia de caracteres descritiva adicional adequada para exibição. Se essa cadeia de caracteres descritiva não estiver disponível por algum motivo, a Autenticação Adobe Pass enviará uma cadeia de caracteres vazia ("). Ele pode ser usado por um MVPD para transmitir mensagens de erro personalizadas ou mensagens relacionadas a vendas. Por exemplo, se um assinante tiver a autorização negada para um recurso, o MVPD pode responder com um
*inRequestDetailedErrorMessage*
como: "No momento, você não tem acesso a esse canal em seu pacote. Se quiser atualizar seu pacote, clique *aqui*." A mensagem é passada pela Autenticação Adobe Pass através desta chamada de retorno para o site do Programador. O Programador tem a opção de exibi-lo ou ignorá-lo. A Autenticação Adobe Pass também pode usar*inRequestDetailedErrorMessage*
para notificar o Programador sobre a condição que pode ter levado a um erro. Por exemplo, "Ocorreu um erro de rede ao se comunicar com o serviço de autorização do provedor".
Acionado por: checkAuthorization(), getAuthorization()
preauthorizedResources(authorizedResources) preauthorizedResources(authorizedResources)
Descrição: Retorno de chamada disparado pelo Habilitador de Acesso que fornece a lista de recursos autorizados retornada após uma chamada para checkPreauthorizedResources()
.
Parâmetros:
- authorizedResources: a lista de recursos autorizados.
Acionado por: checkPreauthorizedResources()
setMetadataStatus(chave, criptografada, dados) setMetadataStatus(key,encrypted,data)
Descrição: Retorno de chamada disparado pelo Habilitador de Acesso que fornece os metadados solicitados por meio de uma chamada getMetadata()
.
Mais Informações: Metadados de Usuário
Parâmetros:
- Chave (Cadeia de Caracteres): a chave dos metadados para os quais a solicitação foi feita.
- criptografado (Booleano): um sinalizador que indica se o "valor" está criptografado ou não. Se isso for "true", o "value" será realmente uma representação JSON Web Encrypted do valor real.
- dados (Objeto JSON): um Objeto JSON com a representação dos metadados. Para solicitações simples ('
TTL_AUTHN
', 'TTL_AUTHZ
', 'DEVICEID
'), o resultado é uma Cadeia de Caracteres (representando o TTL de Autenticação, o TTL de Autorização ou a ID do Dispositivo). No caso de uma solicitação de metadados do usuário, o resultado pode ser um objeto primitivo ou JSON que representa a carga de metadados. A estrutura real dos objetos de metadados do usuário JSON é semelhante ao seguinte:
{
updated: 1334243471,
encrypted: ["encryptedProp"],
data: {
zip: ["12345", "34567"],
maxrating: {
"MPAA": "PG-13",
"VCHIP": "TV-Y",
"URL": "http://exam.pl/e/manage/ratings"
},
householdid: "3456",
uid: "BgSdasfsdk23/dsaf3+saASesadgfsShggssd=",
channelID: ["channel-1", "channel-2"]
}
Por exemplo:
// Implement the setMetadataStatus() callback
function setMetadataStatus(key, encrypted, data) {
if (encrypted) {
//the metadata value is encrypted
//needs to be decrypted by the programmer
data = decrypt(data);
}
alert(key + "=" + data);
}
Acionado por: getMetadata()
Voltar ao início
seletedProvider(result) selectedProvider(result)
Descrição: Implemente esta chamada de retorno para receber o MVPD selecionado no momento e o resultado da autenticação do usuário atual encapsulado no parâmetro result
. O parâmetro result
é um Objeto com as seguintes propriedades:
- MVPD O MVPD selecionado no momento ou nulo se nenhum MVPD foi selecionado.
- AE_State O resultado da autenticação do usuário atual, de "Novo Usuário", "Usuário Não Autenticado" ou "Usuário Autenticado"
Acionado por: getSelectedProvider()