Code in der App#

Fast alles in einer Mini-App wird ohne Code gebaut. Reichen die fertigen Elemente und Blöcke nicht aus, können Sie eigenen Code an drei Stellen hinzufügen:

Der Code läuft auf dem Gerät der Person. Wer sich mit dem Browser auskennt, kann ihn deshalb sehen und fälschen, was der Code an den Server sendet. Legen Sie keine geheimen Schlüssel im Code ab und begrenzen Sie, welche Variablen und Tags der Code ändern darf — mehr dazu unten.

Block „JavaScript“#

Ein Block aus der Kategorie „Daten und Logik“. Erreicht die App den Block, führt sie den Code aus und geht über den Ausgang „Ausgeführt“ oder „Fehler“ weiter.

Platzhalter {{ name }} funktionieren im Code nicht: Lesen Sie Variablenwerte über app.variables.get().

Variablen, die über app.variables.set() geschrieben wurden, und geänderte Tags gehen zusammen mit dem Ausgang des Blocks an den Server.

„Was der Code ändern darf“#

Der Schalter „Nur Aufgelistetes ändern“ ist bei einem neuen Block eingeschaltet. Damit nimmt der Server vom Code nur Folgendes an:

• Variablen aus der Liste „Variablen“;
• Tags aus den Listen „Tags des Bot-Kontakts“ und „Tags des App-Nutzers“ — eine leere Liste bedeutet, dass der Code diese Tags gar nicht ändert;
• die Ergebnis- und die Fehlervariable — sie sind immer erlaubt.

Alles andere verwirft der Server und schreibt in das Fehlerprotokoll „Der Block hat das vom Code Geschriebene verworfen“. Schreibt der Code Namen, die nicht in den Listen stehen, warnen die Einstellungen des Blocks davor und bieten „Zu den Listen hinzufügen“ an.

Schalten Sie die Einschränkung nur aus, wenn nichts von den Variablen und Tags abhängt: Sonst kann sich eine Person zum Beispiel das Tag VIP oder einen Rabatt verschaffen.

Das Objekt app#

Beispiel aus den Einstellungen des Blocks:

// Thema und Bildschirmbreite – in Variablen
const device = app.device
app.variables.set('theme', device.dark ? 'dark' : 'light')

if (app.platform === 'telegram') {
    app.vibrate('success')
}

// Der Rückgabewert kommt in die Ergebnisvariable
return device.width

Fehler im Code sind in der Vorschau in der Browserkonsole sichtbar und landen im Fehlerprotokoll — „JavaScript-Fehler“.

App-Code#

Code für die ganze App: Er wird einmal beim Start ausgeführt, vor dem ersten Bildschirm, und hört auf Ereignisse. Sie öffnen ihn mit dem Button „App-Code“ (Symbol „</>“) in der Leiste über dem Schema. Ist Code hinterlegt, ist das Symbol eingefärbt.

Im Fenster „App-Code“:

• „Code“ — bis zu 100 000 Zeichen;
• „Variablen, die der Code schreiben darf“ — bis zu 50 Namen. Andere Variablen nimmt der Server nicht an;
• eine Übersicht der Ereignisse und ein „Beispiel“ mit dem Button „Beispiel einfügen“.

Der Code wird in der Version gespeichert: Eine neue Version und eine Vorlage erhalten eine Kopie davon. Nach dem Speichern startet eine geöffnete Vorschau neu.

Ereignisse#

• Ein Abonnement auf start, screen und theme erhält sofort den aktuellen Wert — auch wenn es nach await abgeschlossen wurde.
• app.on() gibt eine Funktion zum Abbestellen zurück: const stop = app.on(…); stop(). Es gibt auch app.off(name, handler).
• await app.loadScript('https://…') lädt ein externes Skript: einen Zähler, ein Widget, eine Bibliothek. Die Adresse — nur http:// oder https://.

Alles andere wie beim Block „JavaScript“: app.variables, app.toast, app.alert, app.openLink, app.storage, app.localStorage, app.telegram und weitere. app.contact und app.tags sind hier nur lesbar: Tags zu ändern ist Aufgabe der Tag-Blöcke.

Variablen, die über app.variables.set() geschrieben wurden, gehen mit dem nächsten Ereignis an den Server.

Beispiel aus dem Fenster — Google-Tag:

// Google-Tag einbinden
window.dataLayer = window.dataLayer || []
function gtag() { dataLayer.push(arguments) }
gtag('js', new Date())
gtag('config', 'G-XXXXXXXXXX', {send_page_view: false})
await app.loadScript('https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX')

// Jeder Bildschirm ist ein Seitenaufruf
app.on('screen', ({id, name}) => {
    gtag('event', 'page_view', {page_title: name, page_location: location.origin + '/screen/' + id})
})

// Tippen sind Ereignisse
app.on('event', ({eventId}) => {
    gtag('event', 'tap', {event_id: eventId})
})

Fehler im App-Code — beim Start und in den Handlern — sind in der Konsole sichtbar und landen im Fehlerprotokoll mit dem Grund „Fehler im App-Code“ und dem Aufrufstapel. Derselbe Fehler wird nur einmal geschrieben.

„HTML-Code“: Element und Bildschirm#

Eigenes HTML mit Skripten und Stilen gibt es in zwei Formen:

• Element „HTML-Code“ — in der Gruppe „Widgets“, steht in einem Bereich des Bildschirms neben anderen Elementen;
• Bildschirm „HTML-Code“ — die dritte Bildschirmart nach „Standardfenster“ und „Tabs unten“: Der ganze Bildschirm ist Ihr Code, ohne Kopfzeile und Bereiche. Ein neuer Bildschirm dieser Art erhält sofort ein Beispiel mit einem Button und den Ausgang next. Zu einem modalen Fenster lässt er sich nicht machen.

Der Code läuft in einem isolierten Frame: Sitzung, Daten der App und der übrige Bildschirm sind für ihn nicht erreichbar. Skripte und Stile gehören in den Code. Die Textfarbe übernimmt der Frame aus dem Design der App.

Was der Code im Frame nutzen kann#

Im Schema wird der Code nicht ausgeführt — stattdessen erscheint ein Platzhalter. Im Bildschirm-Editor zeigt der Frame das Ergebnis und startet nach einer Änderung des Codes neu.

Speicher#

Der Speicher auf dem Server ist für jede Plattform eigen: Bei derselben Person ist er in Telegram, MAX und im Browser verschieden.

Einschränkungen#

• Der Code des Blocks „JavaScript“ hat bis zu 20 000 Zeichen, der App-Code und der HTML-Code bis zu 100 000.
• Das Zeitlimit des Blocks „JavaScript“ beträgt bis zu 60 Sekunden.
• Ins Protokoll gelangen höchstens 20 Fehler pro Minute von einem Block.