Guide d’intégration du SDK MA iOS

Versions applicables

Ce guide s’applique au SDK MTMA autonome v5.5.0 et versions ultérieures. Le SDK prend actuellement en charge iOS 10 et versions ultérieures.

Pour les versions antérieures à 5.5.0, consultez le Guide d’intégration avant 5.5.0.

À partir de v5.5.0, le SDK MTMA peut être intégré et initialisé de manière autonome, sans dépendre d’AppPush. MTMA et AppPush disposent de bases de code distinctes. Le SDK officiel reste distribué dans le package Push combiné ; les développeurs peuvent intégrer uniquement MTMA depuis ce package, ou MTMA et MTPush ensemble.

Configurer le projet

Importer le SDK

Importation via CocoaPods

              
                  pod 'MTMA'

    Remarque : si vous ne pouvez pas importer la dernière version, exécutez pod repo update pour mettre à jour le dépôt pod local, puis exécutez à nouveau pod 'MTMA'.

            

• Pour installer une version précise, utilisez la syntaxe suivante (MTMA 5.5.0 dans cet exemple) :

              
                  pod 'MTMA', '5.5.0'

            

Importation manuelle

• Décompressez le package SDK. Dans Xcode, sélectionnez « Add files to 'Your project name'... » et ajoutez MTMA-ios-x.x.x.xcframework au répertoire de votre projet.

Manifeste de confidentialité

Le package SDK contient PrivacyInfo.xcprivacy. Si ce fichier n’est pas automatiquement inclus dans l’application empaquetée, utilisez-le comme référence pour compléter le manifeste de confidentialité de votre application.

Initialiser le SDK

Le SDK MTMA autonome s’initialise avec une MA AppKey, sans attendre l’initialisation ni la réussite de l’inscription d’AppPush.

Avant l’initialisation, dans la console MA, configurez la source de données associée à la MA AppKey du projet courant avec le même iOS Bundle ID que votre application, puis activez cette source. Le SDK lit automatiquement le Bundle Identifier de l’application ; aucun réglage supplémentaire n’est nécessaire. L’initialisation échoue si le Bundle ID n’est pas associé ou ne correspond pas.

Si l’initialisation renvoie 55004 et que message indique packageName is not bound, vérifiez l’association décrite ci-dessus.

              
              - (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    MTMAConfig *config = [[MTMAConfig alloc] init];
    config.appKey = @"votre MA AppKey";
    config.resultCompletion = ^(MTMAInitResult *result) {
        NSLog(@"result：%ld - %@", result.code, result.message);
    };
    [MTMAService start:config];

    return YES;
}

            

Description de certains paramètres

• appKey
  • MA AppKey. Obligatoire ; doit comporter exactement 24 lettres ou chiffres.
  • La MA AppKey et la Push AppKey sont indépendantes et peuvent être identiques ou différentes.
• resultCompletion
  • Callback du résultat d’initialisation. Utilisez result.isSuccess pour déterminer la réussite ; en cas d’échec, fournissez result.code et result.message pour le diagnostic.
  • Pour l’objet renvoyé et ses champs, consultez Classe MTMAInitResult.

L’initialisation nécessite une connexion réseau. Si l’appareil est hors ligne, le SDK attend le rétablissement du réseau puis reprend automatiquement, sans déclencher immédiatement un callback d’échec.

Le SDK permet de répéter l’initialisation et de changer de MA AppKey. Chaque appel valide s’exécute dans l’ordre et reçoit son propre callback. Pour plus de détails, consultez Démarrer les fonctionnalités MA.

Définir les identifiants utilisateur à l’initialisation

Pour définir les identifiants utilisateur à l’initialisation, transmettez-les via MTMAConfig.userID. userID, anonymousID, email et phone sont tous facultatifs. L’exemple suivant utilise userID :

              
              MTMAUserID *userID = [[MTMAUserID alloc] init];
userID.userID = @"member_10001";

MTMAConfig *config = [[MTMAConfig alloc] init];
config.appKey = @"votre MA AppKey";
config.userID = userID;
config.resultCompletion = ^(MTMAInitResult *result) {
    if (result.isSuccess) {
        NSLog(@"Initialisation de MTMA réussie");
    } else {
        NSLog(@"Échec de l’initialisation de MTMA, code=%ld, message=%@", (long)result.code, result.message);
    }
};
[MTMAService start:config];

            

L’initialisation est également possible sans identifiants utilisateur. Sa réussite ne signifie pas que chaque identifiant a été défini avec succès. Pour la validation des champs et les callbacks, consultez Classe MTMAUserID.

Scénarios d’initialisation

Utiliser AppPush avec MTMA

Lors de la configuration d’une source de données mobile dans la console MA, sélectionnez l’utilisation conjointe d’AppPush et choisissez l’application AppPush effectivement intégrée. Initialisez AppPush avec l’AppKey de cette application.

Initialisez MTMA et AppPush séparément. Aucun ordre d’initialisation fixe n’est imposé.

              
              // Initialiser le SDK Push
[MTPushService setupWithOption:launchOptions
                        appKey:pushAppKey
                       channel:channel
              apsForProduction:isProduction
         advertisingIdentifier:nil];

// Initialiser le SDK MTMA
MTMAConfig *config = [[MTMAConfig alloc] init];
config.appKey = maAppKey;
config.resultCompletion = ^(MTMAInitResult *result) {
    NSLog(@"result：%ld - %@", result.code, result.message);
};
[MTMAService start:config];

            

Après la réussite de l’inscription AppPush et l’obtention d’un Push RegistrationID, le SDK MTMA configure automatiquement le canal AppPush. L’absence d’inscription AppPush ou un échec de configuration du canal n’affecte ni l’initialisation MTMA, ni la collecte ou la remontée des événements.

Définir les identifiants de contact du canal

Pour utiliser un service Push tiers, définissez son RID ou Token après la réussite de l’initialisation MTMA.

              
              [MTMAService setChannelValueWithChannelId:136
                                   values:@[@"RID ou Token Push"]
                               completion:^(NSInteger code, NSString *message) {
    NSLog(@"result：%ld - %@", code, message);
}];

            

Description de certains paramètres

• channelId
  • ID du canal Push tiers configuré dans la console MA ; doit être supérieur à 0.
• values
  • Tableau de RID ou Tokens du service Push tiers. Ni le tableau ni ses éléments ne doivent être vides.
  • Rappelez l’API pour mettre à jour la valeur lorsque le RID ou Token change.

Cette API est réservée aux services Push tiers. Pour les contraintes détaillées, consultez Définir les identifiants de contact du canal.

Mise à niveau depuis les versions antérieures

• Le SDK officiel reste distribué dans le package Push combiné. Les projets intégrant déjà AppPush et MTMA n’ont pas besoin de modifier leur procédure d’importation manuelle.
• Après la mise à niveau vers v5.5.0, vous devez définir appKey dans MTMAConfig.
• MTMAConfig.userID et les quatre champs d’identifiant utilisateur sont facultatifs. Traitez-les comme des propriétés optionnelles dans une intégration Swift.
• L’ancien callback completion reste disponible, mais resultCompletion est recommandé. Si les deux sont définis, seul resultCompletion est appelé.
• Push RegistrationID et MA RID correspondent à des identités d’appareil différentes et ne sont pas interchangeables.