คู่มือการผสานรวม SDK MA สำหรับ iOS

เวอร์ชันที่ใช้ได้

คู่มือนี้ใช้กับ SDK MTMA แบบอิสระ v5.5.0 ขึ้นไป ปัจจุบัน SDK รองรับเฉพาะอุปกรณ์ที่ใช้ iOS 10 ขึ้นไป

สำหรับเวอร์ชันก่อน 5.5.0 โปรดดู คู่มือการผสานรวมก่อน 5.5.0

ตั้งแต่ v5.5.0 เป็นต้นไป SDK MTMA สามารถผสานรวมและเริ่มต้นใช้งานได้อย่างอิสระโดยไม่ต้องพึ่งพา AppPush โค้ดของ MTMA และ AppPush แยกจากกัน แต่ SDK ทางการยังคงเผยแพร่ผ่านแพ็กเกจรวม Push คุณสามารถผสานรวมเฉพาะ MTMA จากแพ็กเกจนั้น หรือผสานรวมทั้ง MTMA และ MTPush ได้

กำหนดค่าโปรเจกต์

นำเข้า SDK

นำเข้าผ่าน CocoaPods

              
                  pod 'MTMA'

    หมายเหตุ: หากไม่สามารถนำเข้าเวอร์ชันล่าสุดได้ ให้เรียกใช้ pod repo update เพื่ออัปเดตคลัง pod ในเครื่อง แล้วเรียกใช้ pod 'MTMA' อีกครั้ง

            

• หากต้องการติดตั้งเวอร์ชันที่ระบุ ให้ใช้วิธีต่อไปนี้ (ตัวอย่างใช้ MTMA 5.5.0):

              
                  pod 'MTMA', '5.5.0'

            

นำเข้าด้วยตนเอง

• แตกไฟล์แพ็กเกจ SDK แล้วเลือก “Add files to 'Your project name'...” ใน Xcode เพื่อเพิ่ม MTMA-ios-x.x.x.xcframework ลงในไดเรกทอรีโปรเจกต์

รายการประกาศความเป็นส่วนตัว

แพ็กเกจ SDK มีไฟล์ PrivacyInfo.xcprivacy ให้แล้ว หากไฟล์นี้ไม่ได้รวมอยู่ในแอปที่แพ็กโดยอัตโนมัติ ให้ใช้ไฟล์นี้เป็นข้อมูลอ้างอิงเพื่อเพิ่มรายการประกาศความเป็นส่วนตัวของแอป

เริ่มต้นใช้งาน SDK

SDK MTMA แบบอิสระใช้ MA AppKey ในการเริ่มต้นใช้งาน โดยไม่ต้องรอให้ AppPush เริ่มต้นใช้งานหรือลงทะเบียนสำเร็จ

ก่อนเริ่มต้นใช้งาน ให้กำหนด iOS Bundle ID ของแหล่งข้อมูลที่ตรงกับ MA AppKey ในโปรเจกต์ปัจจุบันบนคอนโซล MA ให้ตรงกับแอป และเปิดใช้งานแหล่งข้อมูลนั้น SDK อ่าน Bundle Identifier ของแอปโดยอัตโนมัติ จึงไม่ต้องตั้งค่าแยก หากยังไม่ได้ผูกหรือค่าไม่ตรงกัน การเริ่มต้นใช้งานจะล้มเหลว

หากการเริ่มต้นใช้งานคืนค่า 55004 และ message ระบุว่า packageName is not bound ให้ตรวจสอบการกำหนดค่าการผูกข้างต้น

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

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

    return YES;
}

            

คำอธิบายพารามิเตอร์บางส่วน

• appKey
  • MA AppKey เป็นค่าที่จำเป็น ต้องประกอบด้วยตัวอักษรหรือตัวเลข 24 ตัว
  • MA AppKey และ Push AppKey เป็นอิสระจากกัน สามารถใช้ค่าเดียวกันหรือคนละค่าได้
• resultCompletion
  • Callback ผลการเริ่มต้นใช้งาน ใช้ result.isSuccess เพื่อตรวจสอบว่าสำเร็จหรือไม่ หากล้มเหลว สามารถใช้ result.code และ result.message เพื่อหาสาเหตุ
  • ดูออบเจ็กต์ที่คืนค่าและคำอธิบายฟิลด์ใน คลาส MTMAInitResult

การเริ่มต้นใช้งานต้องเชื่อมต่อเครือข่าย หากอุปกรณ์ออฟไลน์ SDK จะรอให้เครือข่ายกลับมาแล้วดำเนินการต่อโดยอัตโนมัติ โดยไม่เรียก callback แจ้งความล้มเหลวทันที

SDK รองรับการเริ่มต้นใช้งานซ้ำและการเปลี่ยน MA AppKey การเรียกที่ถูกต้องแต่ละครั้งจะทำงานตามลำดับและมี callback แยกกัน ดูกฎโดยละเอียดใน เริ่มใช้งานฟังก์ชัน MA

ตั้งค่าตัวระบุผู้ใช้ระหว่างการเริ่มต้นใช้งาน

หากต้องการตั้งค่าตัวระบุผู้ใช้ระหว่างการเริ่มต้นใช้งาน ให้ส่งผ่าน MTMAConfig.userID โดย userID, anonymousID, email และ phone เป็นฟิลด์ที่ไม่บังคับทั้งหมด ตัวอย่างต่อไปนี้ใช้ userID:

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

MTMAConfig *config = [[MTMAConfig alloc] init];
config.appKey = @"MA AppKey ของคุณ";
config.userID = userID;
config.resultCompletion = ^(MTMAInitResult *result) {
    if (result.isSuccess) {
        NSLog(@"เริ่มต้นใช้งาน MTMA สำเร็จ");
    } else {
        NSLog(@"เริ่มต้นใช้งาน MTMA ล้มเหลว, code=%ld, message=%@", (long)result.code, result.message);
    }
};
[MTMAService start:config];

            

สามารถเริ่มต้นใช้งานโดยไม่ตั้งค่าตัวระบุผู้ใช้ได้เช่นกัน การเริ่มต้นใช้งานสำเร็จไม่ได้หมายความว่าตั้งค่าตัวระบุทุกรายการสำเร็จ ดูการตรวจสอบฟิลด์และ callback ใน คลาส MTMAUserID

สถานการณ์การเริ่มต้นใช้งาน

ใช้งานร่วมกับ AppPush

เมื่อกำหนดค่าแหล่งข้อมูลมือถือในคอนโซล MA ให้เลือกใช้งานร่วมกับ AppPush และเลือกแอป AppPush ที่ผสานรวมจริง ใช้ AppKey ของแอปที่เลือกเมื่อเริ่มต้นใช้งาน AppPush

MTMA และ AppPush เริ่มต้นใช้งานแยกกัน โดยไม่กำหนดลำดับตายตัว

              
              // เริ่มต้นใช้งาน SDK Push
[MTPushService setupWithOption:launchOptions
                        appKey:pushAppKey
                       channel:channel
              apsForProduction:isProduction
         advertisingIdentifier:nil];

// เริ่มต้นใช้งาน SDK MTMA
MTMAConfig *config = [[MTMAConfig alloc] init];
config.appKey = maAppKey;
config.resultCompletion = ^(MTMAInitResult *result) {
    NSLog(@"result：%ld - %@", result.code, result.message);
};
[MTMAService start:config];

            

เมื่อ AppPush ลงทะเบียนสำเร็จและได้รับ Push RegistrationID แล้ว SDK MTMA จะตั้งค่าช่องทาง AppPush โดยอัตโนมัติ การที่ AppPush ยังไม่ลงทะเบียนหรือการตั้งค่าช่องทางล้มเหลว ไม่กระทบต่อการเริ่มต้นใช้งาน MTMA การเก็บเหตุการณ์ หรือการรายงานเหตุการณ์

ตั้งค่า ID ติดต่อของช่องทาง

หากต้องการใช้ Push ของบุคคลที่สาม ให้ตั้งค่า RID หรือ Token ของผู้ให้บริการนั้นหลังจาก MTMA เริ่มต้นใช้งานสำเร็จ

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

            

คำอธิบายพารามิเตอร์บางส่วน

• channelId
  • ID ของช่องทาง Push ของบุคคลที่สามที่กำหนดไว้ในคอนโซล MA ต้องมากกว่า 0
• values
  • อาร์เรย์ RID หรือ Token ของ Push ของบุคคลที่สาม ทั้งอาร์เรย์และสมาชิกต้องไม่ว่าง
  • เมื่อ RID หรือ Token เปลี่ยน ต้องเรียกอินเทอร์เฟซอีกครั้งเพื่ออัปเดต

อินเทอร์เฟซนี้ใช้สำหรับ Push ของบุคคลที่สามเท่านั้น ดูข้อจำกัดโดยละเอียดใน ตั้งค่า ID ติดต่อของช่องทาง

การอัปเกรดจากเวอร์ชันเก่า

• SDK ทางการยังคงเผยแพร่ผ่านแพ็กเกจรวม Push โปรเจกต์ที่ผสานรวม AppPush และ MTMA ร่วมกันอยู่แล้วไม่ต้องเปลี่ยนวิธีนำเข้าด้วยตนเอง
• หลังจากอัปเกรดเป็น v5.5.0 ต้องตั้งค่า appKey ของ MTMAConfig
• MTMAConfig.userID และฟิลด์ตัวระบุผู้ใช้ทั้งสี่เป็นคุณสมบัติที่ไม่บังคับ ให้จัดการเป็น optional เมื่อผสานรวมด้วย Swift
• ยังคงใช้ callback completion แบบเดิมได้ แต่แนะนำให้เปลี่ยนไปใช้ resultCompletion หากตั้งค่าทั้งสอง จะเรียกเฉพาะ resultCompletion
• Push RegistrationID และ MA RID เป็นข้อมูลระบุอุปกรณ์คนละประเภท ไม่สามารถใช้แทนกันได้