Acasă/Metode

Aplicații · Google Workspace

Cum construim un add-on Google Workspace

Construim fiecare add-on pe Apps Script și CardService, cu cel mai îngust scope care face treaba, apoi îl trecem prin consimțământ, verificare și recenzie. Aprobarea dovedește puțin: ce le-a ținut în funcțiune a fost testarea pe un cont curat, testarea a ceea ce scriu și numărarea oamenilor, nu a locurilor de domeniu.

Actualizat 2026-10-11

La ce folosește

Construim add-on-uri mici pentru Google Docs, Sheets, Slides și Gmail: un panou lateral care face o singură treabă pe fișierul deschis. Până la începutul lui septembrie construiserăm șaisprezece. Aici e metoda noastră de la prima linie de cod până la listarea publică, plus măsurătorile de după.

Cea mai mare parte am învățat-o după aprobare. Aprobarea verifică o listare și un videoclip, nu și dacă un străin poate folosi produsul sau dacă acesta îi lasă datele neatinse.

Construcția: Apps Script, CardService și cel mai îngust scope

1. Apps Script cu CardService. Panoul e construit din widget-uri CardService, nu din HtmlService. Varianta HTML cere script.container.ui, care e scope sensibil. Panoul nativ e îngust și simplu, iar noi acceptăm asta.

2. Alegi familia de scope înainte de funcționalitate. Google are trei trepte. Scope-urile nesensibile, ca documents.currentonly, nu cer verificare OAuth. Cele sensibile, ca gmail.send, cer o rundă de verificare. Cele restricționate, care citesc toată căsuța de e-mail sau tot Drive-ul, adaugă o evaluare de securitate externă, refăcută anual. Treapta o decide familia, nu numărul: unul dintre add-on-urile noastre are trei scope-uri currentonly și a ajuns public fără verificare. Citim clasificarea în prima oră a construcției.

3. Știi ce nu-ți dă scope-ul îngust. Sub *.currentonly ai voie la conținutul fișierului, nu și la datele lui din Drive. Document.getName() aruncă eroare; Sheet.getName(), adică numele unui tab, merge. Diferența nu se vede în cod și e fatală la rulare.

4. Fără backend. Licențele sunt chei semnate, verificate în add-on, iar jurnalizarea excepțiilor e oprită, deci nimic despre utilizator nu pleacă din contul lui. Singura noastră fereastră spre folosire e jurnalul de execuții al Apps Script.

Ecranul de consimțământ, verificarea și listarea

Folosește un proiect Google Cloud standard; cel implicit, creat de Apps Script, nu poate publica. Trece ecranul de consimțământ pe In production: un add-on a fost respins doar pentru asta, fiindcă pe Testing recenzentul a primit error 403: access denied. Unealta noastră de trimitere refuză acum cât timp statusul e Testing.

Scope-urile trebuie să fie identice în trei locuri: manifestul, configurația din Marketplace SDK și ecranul de consimțământ. SDK-ul își ține propria listă, scrisă de mână. Numele trebuie să coincidă în patru: listarea, pagina ei web, ecranul de consimțământ și listarea din SDK.

Pentru un scope sensibil, ordinea e fixă: marca verificată și publicată, apoi verificarea OAuth, apoi trimiterea în Marketplace. O marcă verificată expiră după 7 zile dacă nu apeși și Publish branding, iar redenumirea ecranului de consimțământ o anulează fără niciun semn.

În listare, fiecare marcă Google primește ™, inclusiv Gmail, Calendar și Drive. Descrierea scurtă rămâne în jur de 100 de caractere. Urcă mai multe capturi, la 1280×800; am fost atenționați pentru că aveam una singură. Nu promite o singură permisiune: ecranul de instalare arată trei rânduri, fiindcă Google atașează adresa de e-mail și profilul de bază la orice add-on din Marketplace.

Recenzia

După trimitere vine un e-mail care cere trei lucruri: date de autentificare pentru test, o înregistrare de ecran cap-coadă care arată cum e folosit fiecare scope cerut și verificarea scope-urilor sensibile. Răspundem în același fir: fără date de autentificare, fiindcă nu există login; un videoclip nelistat; cum e folosit scope-ul; și o cheie de licență pentru funcțiile plătite.

În prima noastră rundă, verdictele au venit în 3 până la 8 ore. Din 9 add-on-uri trimise pe 18 și 19 august, 4 au fost aprobate, 2 respinse și 3 erau încă în recenzie. Ambele respingeri au fost de formă: un ™ lipsă și un ecran de consimțământ care nu se potrivea cu listarea.

E-mailul de respingere vine cu vreo 40 de minute înaintea consolei, deci aștepți. Cât timp o ciornă e în recenzie, configurația SDK e înghețată fără să ți-o spună: Save reușește, iar după reîncărcare modificarea a dispărut. O reparație de cod nu cere recenzie nouă: o versiune nouă plus actualizarea deployment-ului publicat ajung imediat la utilizatori. Simpla împingere a codului schimbă doar versiunea de lucru, pe care utilizatorii n-o rulează niciodată.

Capcana: instalarea din magazin nu autorizează scriptul

Instalarea din Marketplace acordă scope-urile add-on-ului; Apps Script cere, separat, autorizarea scriptului. Cât timp lipsește, orice apel de serviciu e refuzat, iar mesajul numește primul apel încercat, deci dă vina pe DocumentApp chiar când scope-ul lui e acordat. Regula noastră, „panoul nu are voie să cadă”, a agravat lucrurile: un try/catch înghițea exact excepția prin care Google desenează butonul de autorizare.

Reparația a trecut prin patru variante în 19 zile. Prima trimitea URL-ul de autorizare al scriptului, fără indiciu de cont, așa că oamenii conectați cu mai multe conturi Google ajungeau la fișierul scriptului; am primit în două zile 12 cereri de acces la codul sursă, de la 7 utilizatori, pe 5 add-on-uri. A doua omitea URL-ul, iar platforma refuza cardul: fundătură pe toate cele 16 add-on-uri, timp de 17 zile. A treia adăuga adresa utilizatorului, care e goală în afara domeniului nostru. A patra nu mai aruncă nimic pentru scope-urile Google; documentația spune că excepția e gândită pentru servicii terțe.

Niciun test n-a prins cele trei variante greșite: fiecare browser de test avea un singur cont conectat, iar mock-ul desena butonul oricum. Le-a prins inboxul. Acum instalăm prin pagina reală din magazin, pe un profil de browser nou, cu un cont care n-a văzut niciodată add-on-ul, și verificăm efectul în document. Testul a arătat că un utilizator nou nu fusese afectat: refuzul lovea granturile existente, după ce schimbaserăm scope-urile. Orice schimbare de scope cere acum o autorizare proaspătă înainte ca reparația să conteze drept făcută.

Testează scrierile pe bune

De patru ori a ajuns un bug la utilizatori fiindcă mock-ul era mai îngăduitor decât platforma. A acceptat un declanșator la sub o oră, o metodă care există doar pe alt widget (recenzentul a văzut Add-on error) și getName(). Ultimul caz ascundea un add-on mort: Outline avea 13 instalări și zero deschideri în 10 zile, fiindcă un câmp nefolosit arunca eroare pe orice document.

Scrierile au fost și mai grave, fiindcă un mock fără stare nu le poate vedea. Change Case citea celulele cu getValues(), care întoarce rezultatul unei formule, și scria blocul înapoi cu setValues(), înlocuind formulele cu rezultatele lor. Panoul spunea că acele celule au rămas neatinse; Undo raporta trei celule restaurate și nu restaura nimic important. În mock, setValues nu făcea nimic. La Alphabetize, 53 de verificări erau verzi, deși sortarea nu rulase niciodată, fiindcă verificarea accepta orice mesaj nevid, inclusiv eroarea.

Regulile de acum: mock-ul aruncă unde aruncă platforma, cu o listă albă de metode pentru fiecare widget; tot ce scrie e testat pe un model cu stare al destinației; aserțiunile verifică forma mesajului de succes; iar fiecare reparație e dovedită prin mutație: pui bug-ul la loc și te uiți cum pică suita. Verificarea se încheie într-un document real, nu în panou.

Măsurarea folosirii: locuri de domeniu față de oameni

Numărul public de utilizatori numără locuri de domeniu: când un administrator instalează pentru o organizație, se adaugă toți angajații. Pe 31 august, totalul nostru public era 2.209; graficul Individual End User Installs din consolă, care numără oamenii ce au instalat singuri, dădea 434. Change Case afișa 1.892 de utilizatori: 2 organizații, 1.875 de locuri și 32 de oameni. Clasamentul nostru era întors pe dos.

Folosirea o citim din API-ul de execuții al Apps Script, care păstrează în jur de 10 zile de istoric, nu 30, așa că eticheta noastră de 30 de zile transforma „nu săptămâna asta” în „niciodată”. Funcțiile pe care raportul nu le recunoștea arătau ca butoane neapăsate de nimeni. Unealta afișează acum fereastra acoperită efectiv și citește handler-ele butoanelor din codul publicat.

Am împărțit „instalări fără folosire” în trei cazuri: nedeschis, deschis fără nicio acțiune, folosit dar neplătit. Doar al treilea ține de ofertă. Iar înainte să crezi un zero, dovedește că instrumentul poate vedea un unu: deschide tu add-on-ul și verifică dacă execuția ta apare.

Unde am greșit

Am tras întâi concluzia că niciun add-on publicat nu putea fi folosit de nimeni. Testul pe cont curat și o recenzie de cinci stele au infirmat-o: defectul lovea doar o parte dintre utilizatori.

Am raportat reparația indiciului de cont drept făcută când exista doar pe calculatorul nostru. A doua zi au venit încă șase cereri de acces, de la cinci oameni, pe patru add-on-uri, niciuna pe singurul add-on desfășurat cu adevărat. Nimic nu e reparat până nu verifici codul servit.

Singura noastră recenzie de o stea spunea că un add-on „nici măcar nu merge”. Panoul gol îi cerea omului să apese Sort, iar singurul buton de pe ecran era Refresh, fiindcă un panou lateral nu vede o selecție făcută după ce s-a deschis. Omul avea dreptate. Acțiunea principală există acum și în starea goală.

Am mai declarat invizibil un add-on instalat corect. Stătea în meniul de overflow More Add-ons; o singură captură de ecran a lămurit lucrurile.

Limite și o listă de verificare

Metoda duce un add-on până la aprobare și îl ține onest. Nu îi aduce utilizatori: de ce multe instalări nu devin folosire e, pentru noi, încă o întrebare deschisă. Consolele se schimbă fără anunț sub uneltele de automatizare, așa că fiecare setare salvată e confirmată prin reîncărcare.

Lista. Treapta scope-ului citită în prima oră. Nicio metadată de fișier sub currentonly. Consimțământul în producție, marca verificată și publicată. Scope-uri identice în trei locuri, nume identic în patru. ™ pe fiecare marcă Google. Instalare pe profil curat, cu un cont care n-a văzut add-on-ul. Mock-uri cu stare, care aruncă precum platforma, testate prin mutație. Reparația verificată pe versiunea servită. Locurile și oamenii citiți separat, iar fiecare zero verificat cu propria execuție.

Întrebări și răspunsuri

Ce scope-uri OAuth cer verificare pentru un add-on Google Workspace?

Verificarea OAuth pentru un add-on Google Workspace depinde de treapta scope-ului. Scope-urile nesensibile, ca documents.currentonly, nu cer verificare OAuth. Cele sensibile, ca gmail.send, cer o rundă de verificare. Cele restricționate, care citesc toată căsuța de e-mail sau tot Drive-ul, adaugă o evaluare de securitate externă, refăcută anual. Treapta o decide familia, nu numărul, așa că un add-on cu mai multe scope-uri currentonly poate ajunge public fără verificare.

De ce a fost respins add-on-ul meu Google Workspace la recenzia din Marketplace?

Respingerile de add-on-uri Google Workspace țin des de formă, nu de cod. Cauze frecvente: ecranul de consimțământ lăsat pe Testing, care îi dă recenzentului o eroare de acces refuzat, simbolul de marcă lipsă de pe o marcă Google și un nume pe ecranul de consimțământ care nu se potrivește cu listarea. Scope-urile trebuie să fie identice în manifest, în configurația Marketplace SDK și pe ecranul de consimțământ.

De ce dă add-on-ul meu Apps Script eroare de permisiune după instalarea din Marketplace?

Un add-on Apps Script poate da eroare după instalarea din Marketplace pentru că instalarea acordă scope-urile add-on-ului, în timp ce Apps Script cere separat autorizarea scriptului. Până atunci, orice apel de serviciu e refuzat, iar mesajul numește primul apel încercat, chiar dacă scope-ul lui e acordat. Un try/catch care înghite excepția ascunde și butonul de autorizare. Orice schimbare de scope cere un test de autorizare proaspăt.

Cum testez un add-on Google Workspace înainte de lansare?

Testarea unui add-on Google Workspace trebuie să se încheie într-un document real, nu în panou. Instalezi add-on-ul prin pagina reală din magazin, pe un profil de browser nou, cu un cont care nu l-a văzut niciodată. Mock-urile trebuie să arunce unde aruncă platforma, cu o listă albă de metode pentru fiecare widget, iar tot ce scrie se testează pe un model cu stare al destinației. Fiecare reparație se dovedește prin mutație.

Arată numărul de utilizatori din Google Workspace Marketplace câți oameni folosesc un add-on?

Numărul de utilizatori din Google Workspace Marketplace nu arată câți oameni folosesc un add-on. El numără locuri de domeniu, deci când un administrator instalează pentru o organizație, se adaugă toți angajații. Graficul din consolă pentru instalările individuale numără oamenii care au instalat singuri, iar folosirea reală vine din jurnalul de execuții Apps Script, care păstrează un istoric scurt. Locurile și oamenii se citesc separat.

Toate metodele