Manuale per sviluppatori di applicazioni

Nota:

L’API V1 di Captivate Prime è ora deprecata. Le API V1 smetteranno di funzionare dal 28 febbraio 2021. Si consiglia di utilizzare le API V2 per interagire con Captivate Prime.

Panoramica

Adobe Captivate Prime è una soluzione di gestione dell’apprendimento self-service ospitata nel cloud e incentrata sugli Allievi. I clienti possono accedere alle risorse di Captivate Prime a livello di programmazione utilizzandone l’API per integrarle con altre applicazioni aziendali. Inoltre, l’API può essere utilizzata dai partner di Adobe per migliorare la proposta di valore di Captivate Prime, estendendone le funzionalità o integrandola con altri servizi o applicazioni.

Scenario di utilizzo

Grazie all’API di Captivate Prime, gli sviluppatori possono creare applicazioni autonome che estendono le funzionalità di Captivate Prime o che integrino Captivate Prime con i flussi di lavoro di altre applicazioni aziendali. Puoi sviluppare un’applicazione Web, un client desktop o un’app per dispositivi mobili utilizzando qualsiasi tecnologia a tua scelta. Come sviluppatore, puoi accedere ai dati delle applicazioni direttamente da Captivate Prime. La distribuzione dell’applicazione che si sta sviluppando è esterna alla piattaforma di Captivate Prime e avrai il pieno controllo sul ciclo di vita dello sviluppo del software man mano che l’applicazione si evolve. In genere, le applicazioni vengono sviluppate da un’organizzazione cliente per l’utilizzo con il proprio account di Captivate Prime e sono quindi private. Inoltre, i partner di Adobe possono creare delle applicazioni generiche con l’API di Captivate Prime, utilizzabili da un’ampia gamma di clienti.

L’API di Captivate Prime

L’API di Captivate Prime si basa sui principi di REST ed espone gli elementi chiave del modello a oggetti di Captivate Prime agli sviluppatori di applicazioni tramite HTTP. Prima di conoscere i dettagli degli endpoint API e dei metodi HTTP, gli sviluppatori possono acquisire dimestichezza con i vari oggetti Captivate Prime, i relativi attributi e le interrelazioni. Una volta compresi i modelli, sarà utile comprendere la struttura delle richieste e delle risposte API e alcuni termini di programmazione comuni utilizzati genericamente nell’API.

Per informazioni dettagliate sui vari metodi ed endpoint API, consulta la°documentazione per le API di Captivate Prime.

Autenticazione API

Quando programmi un’applicazione che effettua chiamate API a Prime, devi registrare l’applicazione utilizzando l’app Amministratore dell’integrazione. 

Le API di Captivate Prime utilizzano il framework OAuth 2.0 per autenticare e autorizzare le applicazioni client. 

Procedura

1. Configurare l’applicazione

Puoi configurare l’applicazione con l’ID client e il segreto client per utilizzare gli endpoint appropriati. Dopo aver registrato l’applicazione, puoi ottenere clientId e clientSecret. È necessario utilizzare GET URL nel browser in quanto autentica gli utenti di Captivate Prime che usano i loro account preconfigurati, ad esempio SSO, Adobe ID e così via. 

GET https://captivateprime.adobe.com/oauth/o/authorize?client_id=<Enter your clientId>&redirect_uri=<Enter a url to redirect to>&state=<Any String data>&scope=<one or more comma separated scopes>&response_type=CODE.

Una volta completata l’autenticazione, il browser reindirizza al redirect_uri indicato nell’URL precedente. Insieme all’URI di reindirizzamento viene aggiunto un codice di parametro.

2. Richiedere un token di aggiornamento dal codice

POST https://captivateprime.adobe.com/oauth/token Content-Type: application/x-www-form-urlencoded

Corpo della richiesta post:

client_id:<Enter your clientId>& client_secret:<Enter your clientSecret>& code:<code from step 1>

3. Ottenere un token di accesso dal token di aggiornamento

URL per ottenere il token di accesso: 

POST https://captivateprime.adobe.com/oauth/token/refresh Content-Type: application/x-www-form-urlencoded

Corpo della richiesta post:

client_id:<Enter your clientId>& client_secret:<Enter your clientSecret>& refresh_token:<refresh token>

URL per verificare i dettagli del token di accesso

GET https://captivateprime.adobe.com/oauth/token/check?access_token=<access_token>

Limitazione di utilizzo

Un token di accesso è valido per sette giorni. Dopo un giorno, devi generare un nuovo token di accesso utilizzando il token di aggiornamento. Se generi un nuovo token di accesso dal token di aggiornamento mentre un token di accesso esistente è ancora valido, verrà restituito il token esistente. 

Alcuni dei termini utilizzati più di frequente nell’API di Captivate Prime sono spiegati come riferimento qui di seguito. 

Include

Gli sviluppatori possono accedere a un singolo modello a oggetti dell’API e a più modelli associati a tale modello. Per accedere ai modelli correlati successivi, devi comprendere la relazione di ciascun modello con gli altri. Il parametro Include consente agli sviluppatori di accedere ai modelli dipendenti. Puoi utilizzare il separatore virgola per accedere a più modelli. Per un esempio di utilizzo e ulteriori dettagli su Include, consulta la sezione degli esempi dei modelli di API in questa pagina. 

Richiesta API

Le richieste API possono essere effettuate tramite una richiesta HTTP. A seconda dell’endpoint e del metodo, lo sviluppatore può scegliere tra vari verbi HTTP come GET, PUT, POST, DELETE, PATCH e così via. Per alcune richieste è possibile passare i parametri di query. Quando si effettua una richiesta per un modello di dati specifico, l’utente può anche richiedere modelli correlati come descritto nelle specifiche delle API in JSON. La struttura di una tipica richiesta API è descritta nell’utilizzo del modello di esempio.

Risposta API

Quando una richiesta API viene effettuata da un client, si ottiene un documento SON in base alla specifica dell’API in JSON. La risposta contiene anche il codice di stato HTTP, che lo sviluppatore può verificare per eseguire i passaggi successivi appropriati nella logica dell’applicazione. La struttura di una tipica risposta API è descritta nell’utilizzo del modello d’esempio.

Errori

Quando una richiesta API ha esito negativo, si ottiene una risposta di errore. Il codice di stato HTTP contenuto nella risposta indica la natura dell’errore. I codici di errore sono rappresentati da dei numeri per ogni modello presente nel riferimento API. 200, 204, 400 e 404 sono alcuni degli errori più comuni rappresentati nelle API che indicano problemi di accesso HTTP.  

Campi

Gli attributi dell’oggetto API e le relative relazioni sono chiamati collettivamente Fields. Per ulteriori informazioni, consulta le API in JSON. Puoi utilizzare Fields come parametro durante le chiamate API per recuperare uno o più attributi specifici dal modello. In assenza del parametro Fields, la chiamata API recupera tutti gli attributi disponibili dal modello. Ad esempio, nella seguente chiamata API, fields[skill]=name recupera solo l’attributo name del modello skill. 

https://captivateprime.adobe.com/primeapi/v2/users/{userId}/userSkills/{id}?include=skillLevel.skill&fields[skill]=name 

Paginazione

A volte, una richiesta API genera un lungo elenco di oggetti da presentare nella risposta. In questi casi, l’attributo di paginazione consente allo sviluppatore di recuperare i risultati in modo sequenziale in termini di più pagine, in cui ogni pagina contiene un intervallo di record. Ad esempio, l’attributo di paginazione in Captivate Prime ti consente di impostare il numero massimo di record da visualizzare in una pagina. Inoltre, puoi definire il valore dell’intervallo dei record da visualizzare sulla pagina. 

Ordinamento

L’ordinamento è consentito nei modelli API. In base al modello, scegli il tipo di ordinamento da applicare ai risultati. L’ordinamento può essere applicato in ordine crescente o decrescente. Ad esempio, se specifichi sort=name, l’ordinamento sarà in ordine crescente in base al nome. Se specifichi sort=-name, l’ordinamento sarà in ordine decrescente in base al nome. Consulta le specifiche dell’API in JSON per ulteriori informazioni

Descrizione dell’uso delle API

Consideriamo uno scenario in cui uno sviluppatore desidera ottenere il nome dell’abilità, i punti massimi assegnati per livello di abilità e i punti guadagnati dall’Allievo per tale abilità.

Un modello userSkill nelle API di Captivate Prime è costituito da id, type, dateAchieved, dateCreated e pointsEarned come attributi predefiniti. Pertanto, quando uno sviluppatore utilizza un metodo GET per acquisire i dettagli del modello userSkill, i dati correnti relativi agli attributi predefiniti vengono visualizzati nell’output di risposta. 

Tuttavia, in questo scenario lo sviluppatore vuole ottenere il nome dell’abilità e i punti del livello di abilità per l’utente. L’API di Captivate Prime ti consente di accedere a queste informazioni correlate utilizzando i campi delle relazioni e di includere i parametri. I modelli associati a userSkill vengono ottenuti nel tag delle relazioni. Puoi ottenere i dettagli di ciascun modello associato chiamando questi modelli insieme a userSkill. Per ottenere queste informazioni, utilizza il parametro°include°con i valori separati da un punto (punto fermo) per ciascuno dei modelli associati. Puoi utilizzare la virgola come separatore per richiedere un altro modello come user include=skillLevel.skill,course

Chiamata API

https://captivateprime.adobe.com/primeapi/v2/users/{userId}/userSkills/{id}?include=skillLevel.skill&fields[skill]=name&fields[skillLevel]=maxCredits&fields[userSkill]=pointsEarned

Ad esempio, userId può essere 746783 e ID userSkills 746783_4426_1. 

Risposta alla chiamata API

{ &quot;links&quot;: {&quot;self&quot;: &quot;https://captivateprime.adobe.com/primeapi/v2/users/746783/userSkills/746783_4426_1?include=skillLevel.skill&fields[userSkill]=pointsEarned&fields[skillLevel]=maxCredits&fields[skill]=name&quot;}, &quot;data&quot;: { &quot;id&quot;: &quot;746783_4426_1&quot;, &quot;type&quot;: &quot;userSkill&quot;, &quot;attributes&quot;: {&quot;pointsEarned&quot;: 5}, &quot;links&quot;: {&quot;self&quot;: &quot;https://captivateprime.adobe.com/primeapi/v2/users/746783/userSkills/746783_4426_1&quot;} }, &quot;included&quot;: [ { &quot;id&quot;: &quot;4426&quot;, &quot;type&quot;: &quot;skill&quot;, &quot;attributes&quot;: {&quot;name&quot;: &quot;Java&quot;}, &quot;links&quot;: {&quot;self&quot;: &quot;https://captivateprime.adobe.com/primeapi/v2/skills/4426&quot;} }, { &quot;id&quot;: &quot;4426_1&quot;, &quot;type&quot;: &quot;skillLevel&quot;, &quot;attributes&quot;: {&quot;maxCredits&quot;: 10} } ] }

Modelli di Captivate Prime

L’API di Captivate Prime consente agli sviluppatori di accedere agli oggetti di Captivate Prime come risorse RESTful. Ogni endpoint API rappresenta una risorsa, in genere un’istanza di oggetto come un Badge o una raccolta di tali oggetti. Gli sviluppatori quindi utilizzano i verbi HTTP quali PUT, GET, POST e DELETE per eseguire le operazioni CRUD su tali oggetti (raccolte).

Nel diagramma seguente sono riportati i vari elementi del modello a oggetti di Captivate Prime nell’API V1.

Modello a oggetti nell’API V1
Modello a oggetti nell’API V1

N. di serie

Oggetto di Captivate Prime

Descrizione

1.      

utente

Utente è il modello chiave di Captivate Prime. Gli Utenti sono in genere gli Allievi interni o esterni di un’organizzazione che utilizzano gli oggetti di apprendimento. Tuttavia, possono svolgere altri ruoli, quali Autore e Manager, insieme al ruolo di Allievo. L’ID utente, il tipo e l’e-mail sono alcuni degli attributi incorporati. 

2.      

corso

Il corso è uno degli oggetti di apprendimento supportati in Captivate Prime, costituito da uno o più moduli. 

3.      

modulo

Il modulo è un elemento fondamentale per la creazione di oggetti di apprendimento in Captivate Prime. I moduli possono essere di quattro tipi diversi, ad esempio la classe, la classe virtuale, l’attività e il ritmo personalizzato. Utilizza questo modello di modulo per ottenere i dettagli di tutti i moduli di un account. 

4.      

certificazione

La certificazione viene assegnata agli studenti in base al completamento dei corsi. Prima di utilizzare le certificazioni, i corsi nell’applicazione sono obbligatori. 

5.      

programmi di apprendimento

I programmi di apprendimento sono corsi progettati specificatamente per soddisfare determinate esigenze di apprendimento degli utenti. In genere, i programmi di apprendimento vengono utilizzati per indirizzare verso obiettivi di apprendimento che coinvolgono tutti i singoli corsi. 

6.      

badge

Un badge è un token che ottengono gli Allievi quando raggiungono dei traguardi specifici durante un corso. 

7.      

abilità

Il modello di abilità è costituito da livelli e crediti. Le abilità possono essere acquisite dagli Allievi dopo il completamento del corso. 

8.      

IscrizioneCertificazione

Questo modello fornisce i dettagli dell’iscrizione di un utente a una singola certificazione.

9.  

IscrizioneCorso

Questo modello fornisce i dettagli dell’iscrizione di un utente a un singolo corso. 

10.  

IstanzaCorso

A un corso possono essere associate una o più istanze. Puoi ottenere l’istanza del corso 

11.  

AbilitàCorso

Un modello AbilitàCorso indica il progresso in un’abilità ottenuta al completamento di un corso.

12.  

ModuloCorso

Un modello ModuloCorso indica come includere un modulo  in un corso. Ad esempio, se il modulo viene utilizzato per la verifica preliminare o per il contenuto.

13.  

IstanzaProgrammaApprendimento

Un programma di apprendimento può essere costituito da più istanze caratterizzate da proprietà simili a quelle di un programma di apprendimento o di istanze personalizzate. 

14.  

risorsa formativa

Le risorse formative sono contenuti didattici accessibili agli Allievi senza alcun requisito di completamento o di iscrizione. Puoi recuperare la data aggiornata, lo stato e le informazioni ID insieme ai modelli correlati, ad esempio la versione della risorsa formativa, gli autori e il livello di abilità. 

15.  

VersioneRisorsaFormativa

Una risorsa formativa può avere una o più versioni in base al numero di download e di revisioni del contenuto. Questo modello fornisce i dettagli di una singola versione della risorsa formativa. 

16.  

IscrizioneIstanzaProgrammaApprendimento

Il programma di apprendimento è costituito da una o più istanze. Gli Allievi possono iscriversi a un’istanza del programma di apprendimento da soli o tramite l’assegnazione dell’Amministratore. Questo modello fornisce i dettagli dell’iscrizione di un utente a una singola istanza del programma di apprendimento. 

17.  

VersioneModulo

Un modulo può avere una o più versioni in base ai caricamenti dei contenuti rivisti. Utilizza questo modello per ottenere informazioni specifiche su qualsiasi versione di un singolo modulo. 

18.  

LivelloAbilità

Un livello di abilità comprende uno o più corsi da svolgere per acquisire un livello con i relativi crediti associati. 

19.  

BagdeUtente

BadgeUtente fa riferimento a un singolo badge relativo a un singolo utente. Contiene dettagli tra cui la data in cui è stato raggiunto, l’UrldiAsserzione e così via. 

20.  

AbilitàUtente

L’AbilitàUtente indica quanto di un singolo livello di abilità sia stato raggiunto da un singolo utente.

Di seguito sono riportati i vari elementi del diagramma della classe di Captivate Prime nell’API V2.

Diagramma della classe nell’API V2
Diagramma della classe nell’API V2

Oggetto di Captivate Prime Descrizione
account Contiene i dettagli di un cliente Prime.
badge Un badge è un token che ottengono gli Allievi quando raggiungono dei traguardi specifici durante un corso. 
catalogo Catalogo è una°raccolta di oggetti di apprendimento.
utente Utente è il modello chiave di Captivate Prime. Gli Utenti sono in genere gli Allievi interni o esterni di un’organizzazione che utilizzano gli oggetti di apprendimento. Tuttavia, possono svolgere altri ruoli, quali Autore e Manager, insieme al ruolo di Allievo. L’ID utente, il tipo e l’e-mail sono alcuni degli attributi incorporati. 
risorsa Viene utilizzato per modellare ogni risorsa di contenuto che un modulo cerca di contenere. Tutte le risorse contenute inuna loResourcesono equivalenti in termini di obiettivo di apprendimento, ma differiscono l’una dall’altra in termini di tipologia di distribuzione o di impostazioni locali del contenuto.
NotificheUtente Questo modello contiene informazioni di notifica relative a un Allievo.
AbilitàUtente L’AbilitàUtente indica quanto di un singolo livello di abilità sia stato raggiunto da un singolo utente.
BagdeUtente BadgeUtente fa riferimento a un singolo badgerelativoa un singolo utente. Contiene dettagli tra cui la data in cui è stato ottenuto,UrlAsserzionee così via. 
abilità Il modello di abilità è costituito da livelli e crediti. Le abilità possono essere acquisite dagli Allievi dopo il completamento del corso. 
LivelloAbilità Un livello di abilità comprende uno o più corsi da svolgere per acquisire un livello con i relativi crediti associati. 
OggettoApprendimento Un oggetto di apprendimento è un’astrazione per vari tipi di oggetti a cui gli utenti possono iscriversi e da cui possono imparare. Attualmente Prime ha quattro tipi di oggetti di apprendimento: corso, certificazione, programma di apprendimentoerisorsa formativa.
IstanzaOggettoApprendimento
Un’istanza specifica di un oggetto di apprendimento.
RisorsaOggettoApprendimento È equivalente al concetto dimodulo. Un corso è composto da unoopiù moduli. In Prime, un modulo può essere distribuito in una serie di modi equivalenti tra loro. Pertanto,loResourcecontiene di fatto tutte queste risorse omologhe.
loResourceGrade
Contiene il risultato dell’utilizzo di una risorsa specifica da parte dell’utente nel contesto di un oggetto di apprendimento a cui è iscritto. Dispone di informazioni quali il tempo trascorsodall’utentenella risorsa, la percentuale di avanzamento, l’esito positivo/negativo e il punteggio ottenuto in qualsiasi test correlato.
calendario
Un oggetto calendario è un elenco deiprossimi corsiin classe o in classe virtuale a cui l’utente può iscriversi.
InformazioniFeedbackL1
Il feedback L1 contiene le risposte fornite dall’Allievo alle domande di feedback associate agli oggetti di apprendimento. In genere viene creato dopo che l’utente ha completato un oggetto di apprendimento°configurato°per raccogliere tali feedback dagli Allievi.
iscrizione
Questa astrazione include i dettagli relativi alla transazione che rappresenta l’assegnazione di un utente specifico a un’istanza specifica dell’oggetto di apprendimento.

Processo di sviluppo delle applicazioni

Prerequisiti

Come sviluppatore, devi creare un account di prova su Prime per avere un accesso completo a tutti i ruoli all’interno di tale account. Per poter scrivere un’applicazione, uno sviluppatore deve creare alcuni utenti e corsi e portare l’account a uno stato ragionevole in modo che l’applicazione in fase di sviluppo possa avere accesso ad alcuni dati di esempio.

Creare ID client e segreto client

  1. Nella pagina di accesso di Amministratore dell’integrazione, fai clic su Applicazioni nel riquadro a sinistra. 

  2. Fai clic su Registra°in alto a destra della pagina per registrare i dettagli dell’applicazione. Viene visualizzata la pagina Registrazione. 

    Registrare un nuovo richiedente
    Registrare un nuovo richiedente

    È obbligatorio compilare tutti i campi di questa pagina. 

    Nome dell’applicazione: inserisci il nome dell’applicazione. Non è obbligatorio utilizzare lo stesso nome dell’applicazione, può essere qualsiasi nome valido. 

    URL: se conosci l’URL esatto in cui è ospitata l’applicazione, puoi menzionarlo. In caso contrario, puoi indicare l’URL della tua azienda. In questo campo è necessario fornire un nome URL valido. 

    Domini di reindirizzamento: inserisci il nome del dominio dell’applicazione a cui desideri reindirizzare l’applicazione di Captivate Prime dopo l’autenticazione OAuth. Qui puoi indicare più URL purché siano validi come http://google.com, http://yahoo.com e così via. 

    Descrizione: inserisci una breve descrizione dell’applicazione. 

    Ambiti: scegli una delle quattro opzioni disponibili per definire l’ambito dell’applicazione. In base alla tua scelta, gli endpoint API di Captivate Prime saranno accessibili per l’applicazione. Ad esempio, se scegli l’accesso in lettura al ruolo di Allievo, tutti gli endpoint API da Allievo di Captivate Prime sono accessibili all’applicazione in sola lettura. 

    Solo per questo account? 
    : se scegli Sì, l’applicazione non sarà visibile ad altri amministratori account.
    No: se scegli No, anche altri amministratori account potranno accedere a questa applicazione, ma dovranno usare l’ID dell’applicazione. L’ID dell’applicazione viene generato e visualizzato nella modalità di modifica dell’applicazione di Captivate Prime. 

    Nota:

    Se scegli l’accesso in lettura e scrittura al ruolo di Amministratore come ambito durante la registrazione dell’applicazione e°l’accesso in lettura al ruolo di Amministratore°durante la creazione delle API, puoi comunque disporre dell’accesso in scrittura per l’applicazione poiché l’ambito di registrazione dell’applicazione sostituisce il flusso di lavoro dell’autorizzazione. 

  3. Dopo aver compilato i dettagli nella pagina di registrazione, fai clic su Registra in alto a destra.

Sviluppo e test delle applicazioni

L’API di Captivate Prime può essere utilizzata dagli sviluppatori per creare qualsiasi applicazione. Gli sviluppatori devono assicurarsi che i propri account siano composti da alcuni utenti e corsi validi. Possono creare alcuni utenti e corsi fittizi e simulare l’attività nell’account di prova per testare la funzionalità dell’applicazione.

Distribuzione delle applicazioni

È consigliabile che l’amministratore di Captivate Prime, o un amministratore dell’integrazione per l’account di produzione, renda l’applicazione disponibile agli utenti all’interno della propria organizzazione. Una volta testata l’applicazione, informa l’amministratore dell’account di produzione. Idealmente, gli amministratori desiderano generare un nuovo ID client e un segreto client per l’applicazione nell’account di produzione ed eseguire i passaggi necessari per integrarli nell’applicazione in modo sicuro. La procedura effettiva di distribuzione delle applicazioni varia da azienda ad azienda e l’amministratore di Captivate Prime della tua organizzazione deve ricevere il supporto del reparto IT/IS per poterla completare.

Approvazione delle applicazioni esterne

Puoi aggiungere delle applicazioni esterne facendo clic su Approva°in alto a destra della°pagina°Applicazioni. Fornisci l’ID dell’applicazione esterna e fai clic su Salva.

Aggiungere un richiedente esterno
Aggiungere un richiedente esterno

Domande frequenti

1. Captivate Prime dispone di un e-commerce integrato?

Adobe Captivate Prime non dispone di un e-commerce integrato. Tuttavia, sono disponibili API che consentono di creare un sistema LMS headless personalizzato e di implementare le funzionalità di e-commerce. 

Logo Adobe

Accedi al tuo account