Guide d'intégration du SDK

Conseils d'utilisation

Ce document est le guide d'intégration standard du SDK HarmonyOS d'EngageLab. Il vise à guider l'utilisation du SDK et suppose que le lecteur maîtrise déjà les bases de DevEco Studio ainsi que des connaissances en programmation HarmonyOS.

Ce guide concerne la version 1.0.0 et ultérieures du SDK HarmonyOS d'EngageLab.

• Actuellement, HarmonyOS API 12 et versions ultérieures sont prises en charge.

Description des fonctionnalités du produit

EngageLab Push (engagelab) est un service de notifications push de bout en bout, permettant au serveur d'envoyer des messages instantanément vers les smartphones des utilisateurs finaux, afin que les développeurs maintiennent un lien actif avec leurs utilisateurs, augmentant ainsi l'engagement et la rétention de l'application. Le client EngageLab Push prend en charge plusieurs plateformes : Android, iOS, HarmonyOS et QuickApp.

Ce SDK HarmonyOS permet aux développeurs d'ajouter rapidement la fonction de notifications push à leur application HarmonyOS via EngageLab.

Fonctionnalités principales

• Maintenir une connexion persistante avec le serveur pour permettre la réception instantanée des messages côté client
• Recevoir les notifications et transmettre les informations pertinentes à l'application du développeur

Caractéristiques principales

• Faible consommation de ressources et d'énergie pour maintenir la connexion côté client
• SDK riche en interfaces, personnalisation de l'apparence des notifications possible
• Serveur à grande capacité et stable

Modes d'intégration

Intégration automatique

Dépendance har

Remarque : Ajoutez dans le fichier oh-package.json5 du module entry

              
              "dependencies": {
    "@engagelab/push": "x.x.x"//Indiquez la version correspondante, par exemple : "@engagelab/push": "1.0.0"
}

            

Remarque 2 : Le har est désormais en bytecode, il faut mettre à jour l'IDE en version 5.0.3.500 ou supérieure et configurer "useNormalizedOHMUrl": true dans le fichier build-profile.json5 au niveau du projet (racine)

              
                  "products": [
      {
        "buildOption": {
          "strictMode": {
            "useNormalizedOHMUrl": true//activer
          }
        },
        "name": "default",
        "signingConfig": "default",
        "compileSdkVersion": "5.0.0(12)",
        "compatibleSdkVersion": "5.0.0(12)",
        "runtimeOS": "HarmonyOS"
      }
    ]

            

Intégration manuelle

Lien de téléchargement de l'archive d'intégration : Aller au téléchargement, contenu de l'archive :

Contenu de l'archive engagelab-hmos-x.x.x-release.zip

• engagelab-hmos-x.x.x-release.har
  • Package principal du service développeur EngageLab.
• doc
  • Documentation
• entry
  • Projet de démonstration hmos, illustrant l'utilisation de base du SDK EngageLab, à utiliser comme référence.

Intégration du fichier har

• Décompressez l'archive engagelab-hmos-x.x.x-release.zip.
• Copiez engagelab-hmos-x.x.x-release.har dans le dossier entry/hars/ de votre projet (le nom du dossier hars peut être personnalisé).

Remarque : Pour référencer engagelab-hmos-x.x.x-release.har, si vous copiez le har dans entry/hars/, ajoutez dans le fichier oh-package.json5 du module entry

              
              "dependencies": {
    "jg_harmony_har": "./hars/engagelab-hmos-x.x.x-release.har" //chemin où se trouve votre har
}

            

Remarque 2 : Le har est désormais en bytecode, il faut mettre à jour l'IDE en version 5.0.3.500 ou supérieure et configurer "useNormalizedOHMUrl": true dans le fichier build-profile.json5 au niveau du projet (racine)

              
                  "products": [
      {
        "buildOption": {
          "strictMode": {
            "useNormalizedOHMUrl": true//activer
          }
        },
        "name": "default",
        "signingConfig": "default",
        "compileSdkVersion": "5.0.0(12)",
        "compatibleSdkVersion": "5.0.0(12)",
        "runtimeOS": "HarmonyOS"
      }
    ]

            

Configuration des informations de la plateforme hmos

Pour activer la fonction de push, il est nécessaire de configurer les informations de la plateforme HarmonyOS.

Principales étapes :

• Récupérez le client_id de l'application correspondante dans le projet sur la plateforme hmos (attention, il ne s'agit pas du client_id du projet)

  Attention : Après avoir créé l'application HarmonyOS, n'oubliez pas de configurer l'empreinte du certificat SHA256/clé publique : cliquez sur "Ajouter une empreinte de clé publique (HarmonyOS API 9 et plus)" après "Empreinte du certificat SHA256/clé publique", puis suivez la documentation « Configurer la signature ».
  

• Activez le service de notifications push sur la plateforme hmos

• Configurez le client_id de l'application dans votre projet local

  Remarque :

  Pour configurer le client_id de l'application localement, ajoutez dans le fichier module.json5 du module entry

  "module": { "metadata": [ { "name": "client_id", "value": "votre_id" } ] }

                
                "module": {
      "metadata": [
          {
              "name": "client_id",
              "value": "votre_id"
          }
      ]
  }
  
              

  Afficher ce bloc de code dans la fenêtre flottante

• Configuration de la signature

  Étape 1 : Préparer le fichier de signature

  https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-publish-app-0000001053223745-V5#section793484619307

  Étape 2 : Demander le certificat de publication

  https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-releasecert-0000001946273961

  Étape 3 : Demander le profil de publication, format .p7b

  https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-releaseprofile-0000001914714796

  Étape 4 : Configurer la signature dans votre projet local, voir l'image

  

Configuration des informations de la plateforme EngageLab

Après les étapes précédentes, il faut également configurer les informations de la plateforme EngageLab.

Principales étapes :

• Créez une application sur la plateforme EngageLab et assurez-vous que les informations suivantes : nom du package et appKey, correspondent à celles de la plateforme EngageLab.

  Remarque 1 :

  Pour configurer le nom du package localement, ajoutez dans le fichier app.json5 du projet AppScope

              
              {
  "app": {
    "bundleName": "votre_bundleName",
  }
}

            

Remarque 2 :

Pour configurer l'appKey EngageLab (générée automatiquement lors de la création de l'application sur la console EngageLab), configurez dans le code comme suit :

              
              export default class MyAbilityStage extends AbilityStage {
  onCreate() {
    EPushInterface.setAppKey("votre_appKey")   //à appeler avant init
  }
}

            

Remarque 3 :

Pour configurer la réception des informations de rappel, configurez dans le code comme suit :

              
              export default class MyAbilityStage extends AbilityStage {
  onCreate() {
    EPushInterface.setCallBackMsg(classe héritée de CallBackMsg)  //recevoir les informations de rappel, à appeler avant init
  }
}

            

Configuration de la page de redirection des notifications

Les notifications peuvent rediriger vers une page spécifique.

Correspondance via uris :

• uris : correspondance de la page via uri, lors de l'envoi, url=votre_scheme://votre_host:votre_port/votre_path
• Remarque : pour la méthode uris, actions doit obligatoirement être une chaîne vide

              
                    {
        "exported": true,
        "skills": [
          {
            "actions": [""], //actions doit obligatoirement être une chaîne vide
            "uris": [
              {
                "scheme": "votre_scheme",
                "host": "votre_host",
                "port": "votre_port",
                "path": "votre_path"
              }
            ]
          }
        ]
      }

            

Correspondance via actions :

• actions : correspondance de la page via actions, renseignez la valeur correspondante, lors de l'envoi actions=votre_actions

              
                    {
        "exported": true,
        "skills": [
          {
            "actions": ["votre_actions"], 
          }
        ]
      }

            

Demander l'activation des notifications

Si les notifications ne sont pas activées, aucune notification ne sera reçue.

Principales étapes :

• Demander sur la page d'accueil

              
              export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    notificationManager.requestEnableNotification().then(() => {
      hilog.info(0x0000, TAG, '%{public}s', `requestEnableNotification success`);
    }).catch((err: Base.BusinessError) => {
      hilog.error(0x0000, TAG, '%{public}s', `requestEnableNotification failed, code is ${err.code}, message is ${err.message}`);
    });
  }
}

            

Configuration des messages personnalisés

Pour traiter les messages personnalisés envoyés via le canal HarmonyOS, suivez les étapes ci-dessous :

Étape 1

• Dans le répertoire src/main/resources/base/profile/ du module du projet, créez le fichier PushMessage.json avec le contenu suivant :

              
              {
  "path": "pushmessage/t_push_message",
  "type": "rdb",
  "scope": "application"
}

            

• path : valeur fixe pushmessage/t_push_message, désigne la base de données et la table.

• type : valeur fixe rdb, indique une base de données relationnelle.

• scope : portée de la base, application (niveau application) ou module (niveau module hap).

• Ajoutez également dans le fichier src/main/module.json5 du module du projet la configuration proxyData suivante :

              
              {
  "module": {
    "proxyData":[{
      "uri": "datashareproxy://{bundleName}/PushMessage",
      "requiredWritePermission": "ohos.permission.WRITE_PRIVACY_PUSH_DATA",
      "metadata":{
        "name": "dataProperties",
        "resource": "$profile:PushMessage"
      }
    }]
  }
}

            

• uri : format fixe datashareproxy://{bundleName}/PushMessage, remplacez {bundleName} par le bundleName de votre application, PushMessage est fixe et ne doit pas être modifié.
• requiredWritePermission : valeur fixe ohos.permission.WRITE_PRIVACY_PUSH_DATA, le service push a besoin de cette permission pour écrire les messages BACKGROUND dans la base.
• metadata : configuration étendue, name doit être dataProperties, resource au format $profile:nom_du_fichier, nom du fichier fixe PushMessage.

Étape 2

• Dans l'ability de votre projet (exemple : PushMessageAbility), importez le module push,
• Attention, seul UIAbility peut recevoir les messages BACKGROUND.

              
              import { UIAbility } from '@kit.AbilityKit';
import { EPushInterface } from '@engagelab/push';
import { pushCommon, pushService } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = 'engagelab-JLog-PushMessageAbility'
export default class PushMessageAbility extends UIAbility {
  onCreate(): void {
    try { // le paramètre de receiveMessage doit être BACKGROUND --- réception des messages personnalisés en arrière-plan
      pushService.receiveMessage('BACKGROUND', this, async (data: pushCommon.PushPayload) => {
        let jg = await EPushInterface.customMessageBackgroundData(data)
        if (jg) { //si true, déjà traité
          return
        }
      });
    } catch (e) {
      hilog.info(0x0000, TAG, '%{public}s', 'BACKGROUND fail:'+JSON.stringify(e));
    }
}

            

• Ajoutez également dans le module abilities du fichier src/main/module.json5 du projet la configuration skills avec actions à action.ohos.push.listener (une seule ability doit définir cette action, si uris est également ajouté, il doit être vide).

              
              "abilities": [
      {
        "name": "PushMessageAbility",
        "srcEntry": "./ets/entryability/PushMessageAbility.ets",
        "launchType": "singleton",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "skills": [
          {
            "actions": [
              "action.ohos.push.listener"
            ]
          }
        ]
      }
]

            

Configuration des messages de notification enrichis

Pour gérer les notifications enrichies, procédez comme suit :

Principales étapes :

Étape 1

• Si le processus n'existe pas, ce flux (processus d'extension de notification) sera utilisé. Vous pouvez y traiter la synthèse vocale et renvoyer un contenu personnalisé (par exemple title, body, etc.) pour remplacer le message courant, puis Push Kit affichera la notification.
• Créez un composant de type ExtensionAbility dans votre projet, héritez de RemoteNotificationExtensionAbility, redéfinissez la méthode onReceiveMessage(), et utilisez EPushInterface.receiveExtraDataMessage pour obtenir les données, exemple :

              
              import { pushCommon, RemoteNotificationExtensionAbility } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { EPushInterface } from '@engagelab/push';

const TAG: string = 'engagelab-JLog-RemoteNotificationExtAbility'

export default class RemoteNotificationExtAbility extends RemoteNotificationExtensionAbility {
  async onReceiveMessage(remoteNotificationInfo: pushCommon.RemoteNotificationInfo): Promise<pushCommon.RemoteNotificationContent> {
    hilog.info(0x0000, TAG, 'onReceiveMessage, remoteNotificationInfo: %{public}s',
      JSON.stringify(remoteNotificationInfo));
    let jMessageExtra = await EPushInterface.receiveExtraDataMessage(this, remoteNotificationInfo);
    hilog.info(0x0000, TAG, 'onReceiveMessage jMessageExtra:' + JSON.stringify(jMessageExtra));
    return {}//Pour modifier la notification, retournez un objet avec les nouvelles données
  }

  onDestroy(): void {
    hilog.info(0x0000, TAG, 'RemoteNotificationExtAbility onDestroy.');
  }
}

            

Ajoutez également dans le module extensionAbilities du fichier src/main/module.json5 du projet la configuration de type et actions pour RemoteNotificationExtAbility (une seule ExtensionAbility, si uris est ajouté, il doit être vide) :

              
              "extensionAbilities": [
  {
    "name": "RemoteNotificationExtAbility",
    "type": "remoteNotification",
    "srcEntry": "./ets/entryability/RemoteNotificationExtAbility.ets",
    "description": "RemoteNotificationExtAbility test",
    "exported": false,
    "skills": [
      {
        "actions": ["action.hms.push.extension.remotenotification"]
      }
    ]
  }
]

            

• type : valeur fixe remoteNotification, indique une ExtensionAbility de notification enrichie.
• actions : valeur fixe action.hms.push.extension.remotenotification, pour recevoir les messages enrichis.

Étape 2

• Si le processus existe, ce flux sera utilisé. Si le processus de votre application existe, aucune notification ne sera affichée, que l'application soit au premier ou en arrière-plan.
• Vous pouvez recevoir les messages enrichis en temps réel via la méthode receiveMessage(), exemple :

              
              import { UIAbility } from '@kit.AbilityKit';
import { EPushInterface } from '@engagelab/push';
import { pushCommon, pushService } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = 'engagelab-JLog-PushMessageAbility'
export default class PushMessageAbility extends UIAbility {
  onCreate(): void {
    try { // le paramètre de receiveMessage doit être IM --- réception des notifications enrichies
      pushService.receiveMessage('IM', this, async (data) => {
        let jg = await EPushInterface.extraMessageBackgroundData(data)
        if (jg) { //si true, déjà traité
          return
        }
      });
    } catch (e) {
      hilog.info(0x0000, TAG, '%{public}s', 'IM fail:'+JSON.stringify(e));
    }
}

            

• Ajoutez également dans le module skills du fichier src/main/module.json5 du module du projet la configuration actions à action.ohos.push.listener (une seule ability doit définir cette action, si uris est également ajouté, il doit être vide) :

              
              "abilities": [
      {
        "name": "PushMessageAbility",
        "srcEntry": "./ets/entryability/PushMessageAbility.ets",
        "launchType": "singleton",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "skills": [
          {
            "actions": [
              "action.ohos.push.listener"
            ]
          }
        ]
      }
]

            

Configuration des messages d'appel VoIP push

Pour gérer les messages d'appel VoIP push, procédez comme suit :

Principales étapes :

Étape 1

• Créez un composant de type UIAbility dans votre projet, par exemple PushMessageAbility.ets (dans src/main/ets/entryability), pour gérer la réception des messages d'appel VoIP, exemple :

              
              import { UIAbility } from '@kit.AbilityKit';
import { EPushInterface } from '@engagelab/push';
import { pushCommon, pushService } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = 'engagelab-JLog-PushMessageAbility'
export default class PushMessageAbility extends UIAbility {
  onCreate(): void {
    try {
      pushService.receiveMessage('VoIP', this, async (data) => {
        let jg = await EPushInterface.voIPMessageBackgroundData(data)
        if (jg) { //si true, déjà traité
          return
        }
      });
    } catch (e) {
      hilog.info(0x0000, TAG, '%{public}s', 'VoIP fail:'+JSON.stringify(e));
    }
  }
}

            

Ajoutez également dans le module abilities du fichier src/main/module.json5 du projet la configuration actions pour PushMessageAbility.

              
              "abilities": [ 
  { 
    "name": "PushMessageAbility", 
    "srcEntry": "./ets/entryability/PushMessageAbility.ets", 
    "launchType": "singleton",
    "description": "PushMessageAbility test", 
    "startWindowIcon": "$media:startIcon",
    "startWindowBackground": "$color:start_window_background",
    "exported": false, 
    "skills": [ 
      { 
        "actions": ["action.ohos.push.listener"]
      }
    ]
  } 
]

            

• actions : doit être action.ohos.push.listener, une seule ability doit définir cette action, si uris est également ajouté, il doit être vide.

Configuration de la fonction « Ne pas afficher au premier plan »

Pour gérer la fonction « Ne pas afficher au premier plan », procédez comme suit :

Principales étapes :

Étape 1

• Créez un composant de type UIAbility dans votre projet, par exemple PushMessageAbility.ets (dans src/main/ets/entryability), pour gérer la réception des messages d'appel VoIP, exemple :

              
              import { UIAbility } from '@kit.AbilityKit';
import { EPushInterface } from '@engagelab/push';
import { pushCommon, pushService } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = 'engagelab-JLog-PushMessageAbility'
export default class PushMessageAbility extends UIAbility {
  onCreate(): void {
    try {
      pushService.receiveMessage('DEFAULT', this, async (data: pushCommon.PushPayload) => {
        let jg = await EPushInterface.defaultMessageBackgroundData(data)
        if (jg) { //si true, déjà traité
          return
        }
      });
    } catch (e) {
      hilog.info(0x0000, TAG, '%{public}s', 'DEFAULT fail:'+JSON.stringify(e));
    }
  }
}

            

Ajoutez également dans le module abilities du fichier src/main/module.json5 du projet la configuration actions pour PushMessageAbility.

              
              "abilities": [ 
  { 
    "name": "PushMessageAbility", 
    "srcEntry": "./ets/entryability/PushMessageAbility.ets", 
    "launchType": "singleton",
    "description": "PushMessageAbility test", 
    "startWindowIcon": "$media:startIcon",
    "startWindowBackground": "$color:start_window_background",
    "exported": false, 
    "skills": [ 
      { 
        "actions": ["action.ohos.push.listener"]
      }
    ]
  } 
]

            

• actions : doit être action.ohos.push.listener, une seule ability doit définir cette action, si uris est également ajouté, il doit être vide.

Activation de la fonction Push

Principales étapes :

• Définir d'abord l'appKey avant init
• Définir d'abord la classe de rappel avant init

              
              export default class MyAbilityStage extends AbilityStage {
  onCreate() {
    EPushInterface.setCallBackMsg(classe héritée de CallBackMsg)//recevoir les informations de rappel//à appeler avant init
    EPushInterface.setAppKey("votre_appKey")//à appeler avant init
    EPushInterface.init(this.context.getApplicationContext())
  }
}

            

Configuration des permissions

• Permissions obligatoires : pour une diffusion plus précise, faites la demande de permission avant d'appeler init pour activer la fonction push.
• À partir de la version v1.0.0, les développeurs n'ont plus besoin de configurer manuellement, le SDK intègre déjà les permissions.

Principales étapes :

• Déclaration des permissions dans le fichier de configuration
• Demander l'autorisation à l'utilisateur, puis appeler init pour activer la fonction push

  Remarque 1 :

  Déclaration des permissions dans le fichier de configuration, ajoutez dans le fichier src/main/module.json5 du module entry

              
              {
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.APP_TRACKING_CONSENT",
        "reason": "$string:reason",
        "usedScene": {
          "abilities": [
            "EntryAbility" //généralement la page d'accueil
          ],
          "when": "always"
        }
      }
    ]
  }
}

            

Remarque 2 :

Demander l'autorisation à l'utilisateur dans EntryAbility, puis activer la fonction push, exemple :

              
              const permissions: Array<Permissions> = ['ohos.permission.APP_TRACKING_CONSENT'];
export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    let context:Context = this.context;
    let atManager:abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
    atManager.requestPermissionsFromUser(context, permissions).then((data: PermissionRequestResult) => {
      // Autorisation accordée //puis activer la fonction push
      EPushInterface.init(this.context.getApplicationContext())
    }).catch((err: BusinessError) => {
      //puis activer la fonction push
      EPushInterface.init(this.context.getApplicationContext())
    })
}

            

Fonctionnalités avancées

Conseils pour obtenir le Registration ID

Toutes les formes de push EngageLab se traduisent finalement par une notification envoyée au Registration ID. Pour faciliter le support client, il est recommandé d'afficher le Registration ID dans des pages peu utilisées de l'application telles que « À propos », « Feedback », « Mon compte », etc., après intégration du SDK.

Exemple de code :

              
              EPushInterface.getRegistrationID();