Questa guida descrive la configurazione e l’utilizzo dell’integrazione MyCharBook per GDRCD.
Il plugin permette di:
- collegare un personaggio GDRCD a MyCharBook;
- salvare e aggiornare la scheda del personaggio;
- sincronizzare campi standard e personalizzati;
- salvare le chat come giocate su MyCharBook;
- salvare le giocate registrate nella pagina delle role.
Caricare i file del plugin nelle rispettive cartelle di GDRCD e di MyCharBook.
La struttura del database viene creata dalla migration:
db_versions/202608272217_GDRCD56_Create_MyCharBook_Tables.php
La migration crea le tabelle per i collegamenti e per la configurazione JSON e inserisce la configurazione predefinita. Non è necessario eseguire manualmente le query SQL.
Modificare quindi i file seguenti: Su config.inc.php aggiungere sui menu del Menu utente
if (MYCHARBOOK_ENABLED) {
$PARAMETERS['user']['mycharbook']['text'] = 'MyCharBook';
$PARAMETERS['user']['mycharbook']['url'] = 'main.php?page=servizi_mycharbook';
$PARAMETERS['user']['mycharbook']['access_level'] = USER;
}e sul menu della Gestione
if (MYCHARBOOK_ENABLED) {
$PARAMETERS['administration']['mycharbook']['text'] = 'Configurazione MyCharBook';
$PARAMETERS['administration']['mycharbook']['url'] = 'main.php?page=gestione_mycharbook';
$PARAMETERS['administration']['mycharbook']['access_level'] = SUPERUSER;
}Su includes/costant_values.inc.php aggiungere:
const MYCHARBOOK_ENABLED = true;
const MYCHARBOOK_SAVE_PLAYS = true;
const MYCHARBOOK_SAVE_CHARACTER = true;
const MYCHARBOOK_SYNC_CHARACTER = true;
const MYCHARBOOK_IMPORT_CHARACTER = true;
const MYCHARBOOK_API_URL = 'https://mycharbook.it';
const MYCHARBOOK_HTTP_TIMEOUT = 15;
const MYCHARBOOK_ENCRYPTION_KEY = 'CHANGE-ME-MYCHARBOOK-KEY';Su pages/frame_chat.inc.php aggiungere dopo il Salva Chat
if (MYCHARBOOK_ENABLED && MYCHARBOOK_SAVE_PLAYS) { ?>
<span class="casella_info">
| <a href="javascript:void(0);" onClick="window.open('mycharbook_save_chat.proc.php','MyCharBook','width=620,height=520,toolbar=no,resizable=yes,scrollbars=yes');">
Salva su MyCharBook
</a>
</span>
<?php }Su pages/scheda/roles/index.inc.php
<?php if ($pg == $_SESSION['login'] && $row['conclusa'] == 1 && MYCHARBOOK_ENABLED && MYCHARBOOK_SAVE_PLAYS) { ?>
<a href="javascript:void(0);" onclick="window.open('mycharbook_save_role.proc.php?id=<?php echo (int) $row['id']; ?>', 'MyCharBookRole', 'width=680,height=560,toolbar=no,resizable=yes,scrollbars=yes');">
Salva su MyCharBook
</a>
<?php } ?>Su header.inc.php aggiungere nella sezione dei css
<link rel="stylesheet" href="themes/<?php echo $PARAMETERS['themes']['current_theme']; ?>/mycharbook.css">Su includes/required.php aggiungere dopo il function.inc.php
require_once(dirname(__FILE__) . '/mycharbook.inc.php');
require_once(dirname(__FILE__) . '/mycharbook_role.inc.php');Caricare infine i nuovi file:
- mycharbook_save_chat.proc.php
- mycharbook_save_role.proc.php
- includes/mycharbook.inc.php
- includes/mycharbook_role.inc.php
- pages/gestione_mycharbook.inc.php
- pages/servizi_mycharbook.inc.php
- themes/advanced/mycharbook.css
MYCHARBOOK_ENABLED
Attiva o disattiva l’intero plugin.
MYCHARBOOK_SYNC_CHARACTER
Abilita l’aggiornamento delle schede già associate.
MYCHARBOOK_IMPORT_CHARACTER
Abilita l’associazione e l’importazione dei dati da MyCharBook.
MYCHARBOOK_SAVE_CHARACTER
Abilita il pulsante di salvataggio della scheda.
MYCHARBOOK_SAVE_PLAYS
Abilita il salvataggio di chat e giocate. È false per impostazione predefinita.
MYCHARBOOK_API_URL
URL base dell’installazione MyCharBook.
MYCHARBOOK_ENCRYPTION_KEY
Chiave utilizzata per cifrare i token nel database GDRCD. Deve essere sostituita con una chiave privata e non deve essere condivisa.
Il pannello è disponibile in:
Gestione → Configurazione MyCharBook
Il pannello salva una configurazione JSON divisa nelle sezioni standard, import e custom:
{
"standard": {},
"import": {},
"custom": []
}I campi standard vengono inviati ai campi corrispondenti del personaggio MyCharBook.
Esempio:
{
"standard": {
"nome": {
"source": "personaggio.nome"
},
"cognome": {
"source": "personaggio.cognome"
},
"sesso": {
"source": "personaggio.sesso"
},
"urlavatar": {
"source": "personaggio.url_img"
},
"miniavatar": {
"source": "personaggio.url_img_chat"
},
"fisica": {
"source": "personaggio.descrizione"
},
"storia": {
"source": "personaggio.storia"
},
"affetti": {
"source": "personaggio.affetti"
}
},
"custom": {}
}La corrispondenza degli avatar è:
GDRCD url_img → MyCharBook urlavatar
GDRCD url_img_chat → MyCharBook miniavatar
Il gestore può configurare direttamente valori fissi, utili per campi come genere, tipo di GDR, PNG e nome della land:
{
"standard": {
"genere": {
"value": "Fantasy"
},
"tipo_gdr": {
"value": "Play by Chat"
},
"png": {
"value": "PG"
},
"gdr": {
"value": "La mia Land"
}
},
"custom": {}
}Quando sono presenti sia value sia source, viene utilizzato value.
Se GDRCD salva un identificativo numerico, è possibile convertirlo nel valore leggibile tramite lookup.
Esempio per la razza:
{
"razza": {
"source": "personaggio.id_razza",
"lookup": {
"table": "razza",
"id_field": "id_razza",
"value_field": "nome"
}
}
}Il valore:
personaggio.id_razza = 3
viene trasformato in:
razza = Elfo
I campi personalizzati vengono organizzati nelle sezioni:
Identità;Aspetto;Statistiche;Extra.
Esempio:
{
"standard": {},
"custom": {
"Identità": {
"Robustezza": {
"source": "personaggio.car0"
}
},
"Aspetto": {
"Cicatrici": {
"source": "personaggio.cicatrici"
}
},
"Statistiche": {
"Forza fisica": {
"source": "personaggio.car1"
}
},
"Extra": {
"Titolo": {
"source": "personaggio.extra"
}
}
}
}Il payload inviato all’API contiene:
{
"custom_fields": {
"Identità": {
"Robustezza": "8"
},
"Extra": {
"Titolo": "Guardiano"
}
}
}L’utente apre:
Menu utente → MyCharBook
L’utente incolla il token API generato su MyCharBook e clicca Salva token.
Il plugin verifica il token tramite api_pairing.php, lo associa alla land e lo salva cifrato nella tabella mycharbook_collegamenti.
Il token è unico per l’integrazione. Non è necessario inserire un secondo token per le giocate: deve essere creato con tutti gli scope necessari alle funzioni attive.
Il token viene inoltre vincolato all’identificativo della land. Se viene copiato in un’altra land, le richieste API vengono rifiutate.
Dopo il collegamento compare:
Salva il personaggio su MyCharBook
Il primo salvataggio usa:
POST /api/characters
I salvataggi successivi usano:
PATCH /api/characters/{id}
L’ID MyCharBook viene memorizzato in GDRCD, evitando la creazione di duplicati su MyCharBook e permettendo di aggiornare i dati del personaggio sul portale.
L’ID della scheda può essere associato anche quando è attivo soltanto il salvataggio delle role. In questo modo le role possono essere collegate a una scheda MyCharBook già esistente senza importare o salvare la scheda del personaggio.
L’utente inserisce l’ID della scheda nella pagina dei servizi e preme Associa personaggio. Se l’ID è già associato, non viene richiesto di reinserirlo.
Il pulsante Disassocia scheda MyCharBook rimuove l’associazione tra il personaggio GDRCD e l’ID MyCharBook. Non elimina la scheda dal portale e non rimuove il token.
Se l’importazione è attiva, l’utente associa prima l’ID della scheda MyCharBook e poi preme Importa personaggio.
L’importazione aggiorna il personaggio GDRCD già esistente utilizzando esclusivamente i mapping presenti nella sezione import della configurazione. Il nome non viene importato.
Se la sezione import manca o non contiene mapping utilizzabili, il plugin mostra un avviso che invita a contattare la gestione: non deve essere mostrata una conferma di importazione quando nessun campo è stato configurato.
Se MYCHARBOOK_SAVE_PLAYS è attivo, il token inserito nella pagina dei servizi deve avere lo scope plays:write.
Il plugin utilizza un solo token per tutte le funzioni abilitate. Il giocatore deve quindi creare su MyCharBook un token con gli scope necessari: characters:write per il salvataggio del personaggio, characters:read per l’importazione e plays:write per il salvataggio di chat e role.
Se il token è associato a un personaggio MyCharBook, la giocata viene collegata automaticamente a quel personaggio. In caso contrario viene salvata senza personaggio.
Il token viene cifrato nel campo principale del collegamento. Lasciando il campo vuoto e salvando, il token viene rimosso.
Quando il salvataggio giocate è attivo, nella chat compare il pulsante:
Salva su MyCharBook
Il pulsante è separato da Salva Chat, che continua a svolgere esclusivamente il salvataggio locale GDRCD.
Il popup consente di inserire:
- titolo;
- descrizione breve.
Il plugin recupera i messaggi della stanza corrente e invia:
POST /api/plays
con un payload simile:
{
"title": "Titolo della giocata",
"description": "Descrizione breve",
"text": "<p><strong>[data] Personaggio:</strong> testo</p>",
"date": "2026-08-21",
"visibility": "private",
"character_id": 524
}Nella pagina:
Scheda → Giocate
per le giocate concluse del personaggio compare:
Salva su MyCharBook
Il popup consente di inserire titolo e descrizione. La data viene automaticamente ricavata da:
segnalazione_role.data_inizio
utilizzando solo la parte relativa alla data, senza l’orario.
Se tra le azioni non è presente il personaggio loggato che sta effettuando la richiesta, il salvataggio viene rifiutato.
api_pairing.php non salva personaggi e non salva giocate. Serve esclusivamente a registrare che un token API appartiene a una determinata integrazione.
Nel flusso attuale viene utilizzata l’azione bind:
POST /api_pairing.php?action=bind
La richiesta deve contenere il token nell’header Authorization:
Authorization: Bearer TOKEN_MYCHARBOOK
Nel corpo della richiesta vengono inviati i dati identificativi della land:
integration_key=identificativo-univoco-della-land
integration_name=Nome della land
integration_url=https://www.esempio.it
integration_key deve essere stabile e univoco per la land. È il valore utilizzato da MyCharBook per distinguere una land da un’altra.
integration_name è il nome leggibile mostrato nei dati dell’integrazione.
integration_url è l’indirizzo della land e permette di riconoscere più facilmente da quale installazione proviene il collegamento.
Quando la richiesta va a buon fine, MyCharBook registra il collegamento e restituisce una risposta simile a:
{
"success": true,
"data": {
"bound": true,
"integration_key": "identificativo-univoco-della-land"
}
}Il plugin esegue questa operazione quando l’utente salva il token nella pagina dei servizi. Se il token è già associato alla stessa land, l’operazione aggiorna il nome e l’URL dell’integrazione senza creare un secondo collegamento.
Un token già associato a una land non può essere utilizzato da un’altra integrazione. Se il token viene revocato su MyCharBook, le richieste successive restituiscono un errore di autenticazione e l’utente deve inserire un nuovo token.
L’associazione del token alla land è distinta dall’associazione dell’ID del personaggio: rimuovere l’ID non rimuove il token e rimuovere il token non elimina la scheda MyCharBook.
Gli errori più comuni sono:
Il token è invalido, revocato o privo dello scope necessario.
Soluzione: generare o inserire un nuovo token.
Il personaggio o la risorsa associata al token non esiste più.
Durante l’aggiornamento della scheda, il plugin prova a crearne una nuova e a salvare il nuovo ID. Per una giocata senza personaggio, verificare invece che il token sia valido e che l’ID eventualmente inviato esista ancora.
Uno o più dati non rispettano i requisiti dell’API.
Possibili cause:
- titolo vuoto;
- valore troppo lungo;
- campo configurato con un formato non valido;
- valore HTML non accettato;
- configurazione JSON non coerente.
Controllare:
- blocco popup del browser;
- disponibilità HTTPS tra GDRCD e MyCharBook;
- estensione cURL o
allow_url_fopendel server PHP; - log PHP del server GDRCD.
GDRCD
│
├── api_pairing.php?action=bind
│ ↓
│ token associato alla land
│
├── POST /api/characters primo salvataggio
├── PATCH /api/characters/id aggiornamenti successivi
└── POST /api/plays chat e giocate
I token vengono cifrati nel database GDRCD.
Quando il personaggio è già stato salvato, il pulsante diventa Aggiorna la tua scheda: le modifiche vengono applicate alla scheda esistente senza crearne una nuova. Se la scheda viene cancellata dal portale MyCharBook, il plugin rileva il codice 404 e la ricrea automaticamente utilizzando lo stesso token. Il pulsante Disassocia scheda MyCharBook rimuove solo l’ID della scheda dal collegamento GDRCD: il token resta attivo e può continuare a essere utilizzato per il salvataggio delle role.