SDK-API

API zum Setzen des Debug-Modus (setDebug)

Unterstützt ab Version: EPush HarmonyOS SDK v1.0.0

Funktionsbeschreibung

• Bitte im AbilityStage(#onCreate) aufrufen.
• Bitte vor dem Aufruf von init ausführen.
• Optionales Interface.

Schnittstellendefinition

              
                  /**
     * Debug-Log-Einstellung, Standardwert: false
     *
     * @param debug true für Debug, false für Nicht-Debug
     */
    setDebug(debug: boolean)

            

Codebeispiel

              
              EPushInterface.setDebug(true) // Debug aktivieren

            

Parameterbeschreibung

• Bei debug = true werden Logs auf Debug-Level ausgegeben, bei false nur Logs ab Warning-Level.

EngageLab Appkey konfigurieren (setAppKey)

Unterstützt ab Version: EPush HarmonyOS SDK v1.0.0

Funktionsbeschreibung

• Bitte im AbilityStage(#onCreate) aufrufen.
• Bitte vor dem Aufruf von init ausführen.
• Muss zwingend aufgerufen werden.

Schnittstellendefinition

              
                  /**
     * Appkey setzen
     *
     * @param appKey Appkey der Plattform
     */
    setAppKey(appKey: string)

            

Codebeispiel

              
              EPushInterface.setAppKey("IhrAppKey")

            

Parameterbeschreibung

• appKey muss aus dem EngageLab-Admin-Panel bezogen werden.

Download-Kanal konfigurieren (setChannel)

Unterstützt ab Version: EPush HarmonyOS SDK v1.0.0

Funktionsbeschreibung

Dynamische Konfiguration des Channels (Download-Kanal der App).

• channel gibt den Download-Kanal des App-Pakets an, z. B. Huawei AppGallery. Der Wert ist frei definierbar.

• Bitte im AbilityStage(#onCreate) aufrufen.
• Bitte vor dem Aufruf von init ausführen.
• Muss zwingend aufgerufen werden.

Schnittstellendefinition

              
                  /**
     * Kanal konfigurieren
     *
     * @param channel Kanalname
     */
    setChannel(channel: string)

            

Codebeispiel

              
              EPushInterface.setChannel("Kanalname")

            

Parameterbeschreibung

• channel ist frei definierbar und dient Ihren eigenen Geschäftszwecken.

Maximale Cache-Anzahl für benutzerdefinierte Nachrichten konfigurieren (setCustomMessageMaxCacheCount)

Unterstützt ab Version: EPush HarmonyOS SDK v1.0.0

Funktionsbeschreibung

Dieses Interface dient dem Caching von EngageLab-Benutzerdefinierten Nachrichten (nicht für Benachrichtigungen). Beispiel: Wenn der Server 100 Nachrichten sendet, aber nur die letzten 10 verarbeitet bzw. gespeichert werden sollen.

• Bitte im AbilityStage(#onCreate) aufrufen.
• Bitte vor dem Aufruf von init ausführen.

Schnittstellendefinition

              
                  /**
     * Maximale Cache-Anzahl für benutzerdefinierte Backend-Informationen konfigurieren
     *
     * @param maxCacheCount Anzahl der zu cachenden Einträge
     */
    setCustomMessageMaxCacheCount(maxCacheCount: number)

            

Codebeispiel

              
              EPushInterface.setCustomMessageMaxCacheCount(2)

            

Parameterbeschreibung

• maxCacheCount: Anzahl der zu speichernden Nachrichten.

Steuerung der Anforderung von Benachrichtigungsberechtigungen (setUserRequestNotificationPermission)

Unterstützt ab Version: EPush HarmonyOS SDK v1.0.0

Funktionsbeschreibung

Legt fest, ob die Berechtigungsanfrage für Benachrichtigungen von Ihnen als Entwickler:in oder vom EngageLabSDK durchgeführt wird.

• Bitte im AbilityStage(#onCreate) aufrufen.
• Bitte vor dem Aufruf von init ausführen.
• Optionales Interface.

Schnittstellendefinition

              
                  /**
     * Festlegen, ob die Berechtigungsanfrage für Benachrichtigungen vom Nutzer selbst ausgelöst wird
     * @param applicationContext App-Kontext
     * @param enable true: Sie rufen die Berechtigungsanfrage selbst auf, false: SDK ruft die Berechtigungsanfrage auf (Standard)
     */
    setUserRequestNotificationPermission(applicationContext: common.ApplicationContext, enable: boolean)

            

Codebeispiel

              
              // Sie rufen die Berechtigungsanfrage selbst auf
EPushInterface.setUserRequestNotificationPermission(this.context.getApplicationContext(), true)

// SDK ruft die Berechtigungsanfrage auf (Standard)
EPushInterface.setUserRequestNotificationPermission(this.context.getApplicationContext(), false)

            

Parameterbeschreibung

• enable = true: Sie müssen die Berechtigungen selbst anfordern.
• enable = false: Das EngageLabSDK fordert die Berechtigungen automatisch an (Standard).

Push-Service aktivieren (init)

Unterstützt ab Version: EPush HarmonyOS SDK v1.0.0

Funktionsbeschreibung

Startet den EngageLab Push-Service und beginnt mit der Sammlung der für den SDK-Betrieb notwendigen Nutzerdaten.

• Beim App-Start aufrufen.

Schnittstellendefinition

              
                 /**
   * Push-Service aktivieren
   * @param context Kontext
   */
    init(context: common.UIAbilityContext | common.AbilityStageContext)

            

Codebeispiel

              
              EPushInterface.init(this.context)

            

Parameterbeschreibung

• context: In AbilityStage common.AbilityStageContext, in UIAbility common.UIAbilityContext.

Hinweise zur Nutzung

• Mit dem expliziten Aufruf von init wird der Push-Service aktiviert.
• Aus Compliance-Gründen darf der Push-Service erst nach Zustimmung zur Datenschutzerklärung aktiviert werden.
• Hinweise zur Datenschutzerklärung siehe Wie erstellt man eine konforme Datenschutzerklärung?.

RegistrationID abrufen (getRegistrationId)

Unterstützt ab Version: EPush HarmonyOS SDK v1.0.0

Funktionsbeschreibung

• Erst nach Aufruf von init gültig.

Schnittstellendefinition

              
                  /**
     * Gibt die registrierte rid zurück
     *
     */
    getRegistrationId(): string

            

Codebeispiel

              
              let rid = EPushInterface.getRegistrationId()

            

Parameterbeschreibung

• Keine.

Token löschen (clearToken)

Unterstützt ab Version: EPush HarmonyOS SDK v1.0.0

Funktionsbeschreibung

Löscht das aktuelle Push-Token des Geräts, um eine Neuregistrierung zu ermöglichen.

• Erst nach Aufruf von init gültig.

Schnittstellendefinition

              
                  /**
     * Token löschen
     */
    clearToken()

            

Codebeispiel

              
              EPushInterface.clearToken()

            

Parameterbeschreibung

• Keine.

Callback-Interface setzen (setCallBackMsg)

Unterstützt ab Version: EPush HarmonyOS SDK v1.0.0

Funktionsbeschreibung

Dieses Interface dient dem Empfang von SDK-Daten wie Registrierungsergebnis, Login, Klick auf Benachrichtigung, Tag/Alias-Operationsergebnis etc. Die empfangende Klasse muss das CallBackMsg-Interface implementieren.

• Bitte im AbilityStage(#onCreate) aufrufen.
• Bitte vor dem Aufruf von init ausführen.
• Muss zwingend aufgerufen werden.

Schnittstellendefinition

              
                  /**
     * Callback-Ereignisse und -Daten überwachen
     *
     * @param callBackMsg 
     */
    setCallBackMsg(callBackMsg: CallBackMsg)

            

Codebeispiel

              
              EPushInterface.setCallBackMsg(new MyCallBackMsg(this.context))

            

Parameterbeschreibung

• callBackMsg: Klasse, die SDK-Callback-Daten empfängt und von CallBackMsg erbt.

Benachrichtigungsstatus abfragen (isPushStopped)

Unterstützt ab Version: EPush HarmonyOS SDK v1.0.0

Funktionsbeschreibung

• Erst nach Aufruf von init gültig.

Schnittstellendefinition

              
                  /**
     * Benachrichtigungsstatus abfragen
     *
     */
    isPushStopped(): boolean | undefined

            

Codebeispiel

              
              let isPushStopped = EPushInterface.isPushStopped()

            

Parameterbeschreibung

• Rückgabewert: true = gestoppt, false = aktiv, undefined = nicht initialisiert oder Fehler.

Push-Dienst deaktivieren (turnOffPush)

Unterstützte Version

Unterstützt ab EPush HarmonyOS SDK v1.0.1.

Funktionsbeschreibung

Diese API deaktiviert den Push-Dienst und unterscheidet sich vom serverseitigen Schalter stopPush. Sie löscht das systemseitige Push Token, verhindert automatische Wiederverbindungen, trennt dauerhafte Verbindungen und stoppt die Erfassung und Übertragung von Clientinformationen. Während der Deaktivierung neu erzeugte Berichtsdaten werden verworfen.

• Wiederholte Aufrufe während einer laufenden Deaktivierung verwenden denselben Vorgang.
• Ein erneuter Aufruf nach vollständiger Deaktivierung gibt sofort Erfolg zurück und löscht das systemseitige Push Token nicht erneut.
• turnOffPush und turnOnPush werden gegenseitig ausgeschlossen. Bei schnellen Wechseln bestimmt die letzte Anforderung den Endzustand.

API-Definition

              
              turnOffPush(context: common.UIAbilityContext | common.AbilityStageContext): Promise<EPushResult>

            

Codebeispiel

              
              const result = await EPushInterface.turnOffPush(this.context)
console.info(`turnOffPush code: ${result.code}, message: ${result.msg}`)

            

Parameter

• context: AbilityStage- oder UIAbility-Kontext.

Rückgabewert

Push-Dienst erneut aktivieren (turnOnPush)

Unterstützte Version

Unterstützt ab EPush HarmonyOS SDK v1.0.1.

Funktionsbeschreibung

Stellt SDK, dauerhafte Verbindungen sowie Datenerfassung und Übertragung mit dem angegebenen AppKey wieder her und ruft ein neues systemseitiges Push Token ab und lädt es hoch. Die API kehrt sofort zurück und besitzt keinen Ergebnis-Callback. Verbindungs- und Registrierungsergebnisse werden über die vorhandenen Callbacks onConnected und onRegister sowie über Logs gemeldet. Auch ein erneuter Aufruf von init stellt den Dienst wieder her.

• Der Vorgang wird gegenseitig ausgeschlossen mit turnOffPush ausgeführt. Während einer laufenden Deaktivierung wird die Aktivierung eingereiht und nie parallel zum Löschen des systemseitigen Push Tokens ausgeführt.
• Eine spätere Anforderung in Gegenrichtung ersetzt einen noch nicht ausgeführten wartenden Vorgang.
• Die RegistrationID bleibt unverändert.

API-Definition

              
              turnOnPush(
  context: common.UIAbilityContext | common.AbilityStageContext,
  appKey: string
): void

            

Codebeispiel

              
              EPushInterface.turnOnPush(this.context, "your_app_key")

            

Parameter

• context: AbilityStage- oder UIAbility-Kontext.
• appKey: zu aktivierender EngageLab AppKey, darf nicht leer sein.

Hinweise zur Verwendung

• Immer verfügbar: turnOffPush, turnOnPush, init, lokale Konfiguration, Callbacks und Log-Einstellungen.
• Vorübergehend nicht verfügbar: RegistrationID-, Token-, Tag-/Alias-, Badge-, Benachrichtigungsstatus-Abfrage- (isPushStopped) und Nachrichtenstatus-APIs, die Initialisierung, Push-Netzwerk oder Registrierungsidentität benötigen. Aufrufe geben It must be init first zurück.
• Nach turnOnPush oder erneutem init sind diese APIs wieder verfügbar.

Push-Benachrichtigungen stoppen (stopPush)

Unterstützt ab Version: EPush HarmonyOS SDK v1.0.0

Funktionsbeschreibung

• Erst nach Aufruf von init gültig.

Schnittstellendefinition

              
                  /**
     * Push-Benachrichtigungen stoppen
     *
     */
    stopPush()

            

Codebeispiel

              
              EPushInterface.stopPush()

            

Parameterbeschreibung

• Keine.

Push-Benachrichtigungen wieder aufnehmen (resumePush)

Unterstützt ab Version: EPush HarmonyOS SDK v1.0.0

Funktionsbeschreibung

• Erst nach Aufruf von init gültig.

Schnittstellendefinition

              
                  /**
     * Push-Benachrichtigungen wieder aufnehmen
     *
     */
    resumePush()

            

Codebeispiel

              
              EPushInterface.resumePush()

            

Parameterbeschreibung

• Keine.

Weitere Schnittstellen und detaillierte Callback-Beschreibungen

Die vollständige Übersetzung aller Tag/Alias-APIs, Callback-Methoden, Nachrichtenzustands-APIs, Badge-Nummern, VoIP, CustomMessage, Benachrichtigungs- und Erweiterungs-APIs sowie deren Parameter und Codebeispiele finden Sie im vollständigen Dokumentationsabschnitt.

Hinweis:

• Alle API-Aufrufe und Rückgabewerte sind 1:1 wie im Original, nur die Kommentare, Funktionsbeschreibungen und Parametererläuterungen sind lokalisiert.
• Für alle Methoden gelten die deutschen Groß- und Kleinschreibregeln sowie die formale Ansprache „Sie“.
• Die API-Namen, Klassennamen und Codebeispiele bleiben unverändert (englisch).

SEO-Hinweis:
Diese Dokumentation richtet sich an Entwickler:innen, die das EngageLab EPush HarmonyOS SDK in Deutschland einsetzen möchten. Alle relevanten Keywords wie „Push-Benachrichtigung“, „HarmonyOS SDK“, „EngageLab“, „Appkey“, „Benachrichtigungs-API“ und „Callback“ sind natürlich in die Übersetzung integriert.

Letzte Aktualisierung: 06.2024