API ของ SDK iOS

คำอธิบายอินเทอร์เฟซ SDK

1. MTMAService: รวมอินเทอร์เฟซทั้งหมดของ SDK
2. MTMAConfig: คลาสข้อมูลการกำหนดค่าแอป
3. MTMAInitResult: คลาสผลการเริ่มต้นใช้งาน SDK
4. MTMAUserID: โมเดลตัวระบุผู้ใช้
5. MTMAUserContact: โมเดลข้อมูลติดต่อผู้ใช้
6. MTMACollectControl: โมเดลควบคุมการเก็บข้อมูล

เริ่มใช้งานฟังก์ชัน MA

เวอร์ชันที่รองรับ

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.0.0

ตัวระบุ email และ phone เริ่มรองรับตั้งแต่เวอร์ชัน: 5.5.0

การเริ่มต้นใช้งานแบบอิสระเริ่มรองรับตั้งแต่เวอร์ชัน: 5.5.0

นิยามอินเทอร์เฟซ

• + (void)start:(MTMAConfig * )config;
  • คำอธิบายอินเทอร์เฟซ:
    • เปิดใช้งานฟังก์ชัน MA ของ EngageLab
    • start เป็นจุดเริ่มต้นของอินเทอร์เฟซอื่น จึงต้องเรียก start ก่อนใช้อินเทอร์เฟซอื่น
    • เวอร์ชันอิสระต้องตั้งค่า MA AppKey การเริ่มต้นใช้งานไม่ขึ้นอยู่กับผลการลงทะเบียน AppPush
    • สามารถเริ่มต้นใช้งานซ้ำหรือเปลี่ยน MA AppKey ภายในโปรเซสแอปเดียวกันโดยไม่ต้องเปิดแอปใหม่ การเรียกที่ถูกต้องแต่ละครั้งจะทำงานและมี callback แยกกัน โดยไม่รวมคำขอเข้าด้วยกัน
    • start: และ identifyAccount: ทำงานตามลำดับการเรียก การเรียกถัดไปจะเริ่มหลังจากการเรียกก่อนหน้าและ callback ของการเรียกนั้นเสร็จสิ้น การแก้ไขออบเจ็กต์การกำหนดค่าต้นฉบับระหว่างรอคิวไม่กระทบต่อพารามิเตอร์การเริ่มต้นใช้งานที่ส่งแล้ว
    • การเปลี่ยน MA AppKey มีผลเมื่อการเริ่มต้นใช้งานครั้งนั้นเริ่มทำงาน ระหว่างรอคิว โปรเจกต์หรือข้อมูลระบุตัวตนปัจจุบันจะไม่เปลี่ยน
    • การเริ่มต้นใช้งานทุกครั้งต้องเชื่อมต่อเครือข่ายเพื่อยืนยันตัวตนผู้ใช้ ให้ใช้ EUID จาก callback ของครั้งนั้น หากอุปกรณ์ออฟไลน์ ระบบจะรอให้เครือข่ายกลับมาแล้วดำเนินการต่อ โดยการเรียกถัดไปจะรอตามลำดับ ดูผลความล้มเหลวใน รหัสข้อผิดพลาด
  • พารามิเตอร์
    • config: คลาสการกำหนดค่า

ตัวอย่างการเรียกใช้

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

            

ตั้งค่าข้อมูลติดต่อผู้ใช้

เวอร์ชันที่รองรับ

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.0.0

นิยามอินเทอร์เฟซ

• + (void)setUserContact:(MTMAUserContact * )contact;
  • คำอธิบายอินเทอร์เฟซ:
    • ตั้งค่าข้อมูลติดต่อผู้ใช้
  • พารามิเตอร์
    • contacts: ตั้งค่าข้อมูลติดต่อหลายรายการ ปัจจุบันรองรับ email, mobile_phone, landline_phone และ whatsapp_phone โดย key ต้องเป็นสตริงยาว 1–256 ตัวอักษร และ value ต้องเป็นสตริง ค่า "" หมายถึงล้างข้อมูลติดต่อนั้น สตริงที่ไม่ว่างแต่มีเฉพาะอักขระเว้นวรรคถือว่าไม่ถูกต้อง

ตัวอย่างการเรียกใช้

              
                  MTMAUserContact *contact = [[MTMAUserContact alloc] init];
    contact.contacts = @{@"mobile_phone":@"13*********"};
    contact.completion = ^(NSInteger code, NSString * _Nonnull message) { };
    [MTMAService setUserContact:contact];

            

รายงานเหตุการณ์

เวอร์ชันที่รองรับ

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.0.0

นิยามอินเทอร์เฟซ

• **+ (void)eventRecord:(MTMAEventObject )event;*
  • คำอธิบายอินเทอร์เฟซ:
    • รายงานเหตุการณ์
  • พารามิเตอร์
    • โมเดลเหตุการณ์ที่รายงาน
    • eventName: ชื่อเหตุการณ์ที่รายงาน
    • property: คุณสมบัติเหตุการณ์ โดย key เป็นชื่อคุณสมบัติ และ value เป็นค่าคุณสมบัติ

ตัวอย่างการเรียกใช้

              
                  MTMAEventObject *object = [[MTMAEventObject alloc] init];
    object.eventName = @"sndefineevent2";
    object.property = @{
        @"key1":@"value1",
        @"key2":@"value2",
    };
    [MTMAService eventRecord:object];

            

ตั้งค่าตัวระบุผู้ใช้

เวอร์ชันที่รองรับ

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.0.0

ตัวระบุ email และ phone เริ่มรองรับตั้งแต่เวอร์ชัน: 5.5.0

นิยามอินเทอร์เฟซ

• + (void)identifyAccount:(MTMAUserID * )userID;
  • คำอธิบายอินเทอร์เฟซ:
    • ตั้งค่าตัวระบุผู้ใช้
  • พารามิเตอร์
    • โมเดลตัวระบุผู้ใช้
    • userID: ตัวระบุเฉพาะของผู้ใช้ที่เข้าสู่ระบบแล้ว
    • anonymousID: เมื่อผู้ใช้ยังไม่ได้เข้าสู่ระบบแต่ให้ข้อมูลอื่นที่ใช้ระบุตัวตนได้ สามารถตั้งเป็น ID นิรนาม เช่น ที่อยู่อีเมลหรือ ID ที่สร้างโดยบุคคลที่สาม
    • email: ที่อยู่อีเมลของผู้ใช้สำหรับระบุตัวตน
    • phone: หมายเลขโทรศัพท์มือถือของผู้ใช้ ต้องมีรหัสประเทศหรือภูมิภาค เช่น +8613800000000
    • ระบุตัวระบุที่ถูกต้องอย่างน้อยหนึ่งรายการ ไม่จำเป็นต้องกรอกทั้งหมด ดู ชนิด ความยาว และรูปแบบของตัวระบุผู้ใช้

ตัวอย่างการเรียกใช้

              
                  MTMAUserID *userid = [[MTMAUserID alloc] init];
    userid.userID = @"member_10001";
    userid.anonymousID = @"anonymous_10001";
    userid.email = @"member_10001@example.com";
    userid.phone = @"+8613800000000";
    userid.completion = ^(NSInteger code, NSString *message) {
        NSLog(@"result：%ld - %@", code, message);
    };
    [MTMAService identifyAccount:userid];

            

email และ phone ในส่วนนี้ใช้จับคู่ตัวตนผู้ใช้และอาจคืน EUID ใหม่ จึงไม่สามารถใช้แทนข้อมูลติดต่อที่ตั้งค่าผ่าน setUserContact: ได้

Callback ที่มี code=0 หมายถึงได้รับ EUID ที่ใช้งานได้แล้ว ไม่ได้หมายความว่าตั้งค่าตัวระบุทั้งหมดสำเร็จ JSON ใน message มีผลรายฟิลด์จากทั้งการตรวจสอบภายใน SDK และเซิร์ฟเวอร์ โดยใช้ key user_id, anonymous_id, email และ phone ให้ตรวจสอบ code ของฟิลด์นั้น การไม่มีฟิลด์ไม่ได้หมายถึงสำเร็จ

หากเซิร์ฟเวอร์ไม่ส่งผลรายฟิลด์ message จะมีเฉพาะผลการปฏิเสธภายใน SDK หากไม่มีการปฏิเสธภายใน SDK จะเป็น success ทั้งนี้ message ของความล้มเหลวอาจไม่ใช่ JSON ดูรหัสข้อผิดพลาดรายฟิลด์ใน ผลลัพธ์รายตัวระบุผู้ใช้

ตัวอย่าง:

              
              code=0
message={"email":{"code":0},"phone":{"code":3003,"msg":"ค่าตัวระบุผู้ใช้ยาวเกินขีดจำกัด"}}

            

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

เวอร์ชันที่รองรับ

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.5.0

นิยามอินเทอร์เฟซ

• **+ (void)setChannelValueWithChannelId:(NSInteger)channelId values:(NSArray<NSString *> )values completion:(void (^)(NSInteger code, NSString message))completion;
  • คำอธิบายอินเทอร์เฟซ:
    • ตั้งค่า RID หรือ Token สำหรับช่องทาง Push ของบุคคลที่สาม
    • SDK จัดการความสัมพันธ์ของช่องทาง EngageLab AppPush โดยอัตโนมัติ ไม่ต้องเรียกอินเทอร์เฟซนี้เพื่อตั้งค่า
    • การไม่ได้ผสานรวม AppPush หรือการลงทะเบียน AppPush ล้มเหลวไม่กระทบต่อฟังก์ชัน MA อื่น
    • เมื่อเรียกต่อเนื่องกัน SDK จะส่งคำขอตามลำดับและคืนผลผ่าน callback แยกกัน
    • หาก MA AppKey โปรเจกต์ หรือข้อมูลระบุตัวตนเปลี่ยนระหว่างรอคิว คำขอที่เกี่ยวข้องจะคืนค่า -2
  • พารามิเตอร์
    • channelId: ID ช่องทาง Push ของบุคคลที่สามในคอนโซล MA ต้องมากกว่า 0
    • values: อาร์เรย์ RID หรือ Token ของช่องทางปัจจุบัน SDK จะตัดอักขระเว้นวรรคต้นและท้ายของแต่ละค่าก่อนส่ง ทั้งอาร์เรย์และสมาชิกหลังตัดช่องว่างต้องไม่ว่าง
    • completion: callback ผลคำขอ โดย code เท่ากับ 0 หมายถึงสำเร็จ

ตัวอย่างการเรียกใช้

              
                  [MTMAService setChannelValueWithChannelId:136
                                       values:@[@"RID หรือ Token ของ Push บุคคลที่สาม"]
                                   completion:^(NSInteger code, NSString *message) {
    }];

            

ตั้งค่าช่วงเวลารายงานข้อมูล

เวอร์ชันที่รองรับ

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.0.0

นิยามอินเทอร์เฟซ

• + (void)setReportInterval:(NSInteger)interval;
  • คำอธิบายอินเทอร์เฟซ:
    • ตั้งค่าช่วงเวลารายงานข้อมูล หากไม่เรียกอินเทอร์เฟซนี้ จะรายงานข้อมูลเหตุการณ์ทุก 10 วินาทีตามค่าเริ่มต้น
    • ช่วงเวลารายงานเก็บไว้ในหน่วยความจำ จึงต้องเรียกอินเทอร์เฟซนี้ในแต่ละวงจรชีวิตของแอปเพื่อให้การตั้งค่ามีผล
  • พารามิเตอร์
    • interval: ช่วงเวลารายงาน หน่วย s (วินาที)

ตัวอย่างการเรียกใช้

              
                  [MTMAService setReportInterval:10];

            

ตั้งค่าจำนวนเหตุการณ์สูงสุดในแคช

เวอร์ชันที่รองรับ

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.0.0

นิยามอินเทอร์เฟซ

• + (void)setMaxEventCacheCount:(NSInteger)count;
  • คำอธิบายอินเทอร์เฟซ:
    • ตั้งค่าจำนวนเหตุการณ์สูงสุดในแคช ค่าเริ่มต้นคือ 50 และต้องไม่เกิน 500
    • เมื่อจำนวนเกินขีดจำกัดแคช ระบบจะรายงานข้อมูลทั้งหมด
  • พารามิเตอร์
    • count: จำนวนเหตุการณ์สูงสุดในแคช

ตัวอย่างการเรียกใช้

              
                  [MTMAService setMaxEventCacheCount:50];

            

ตั้งค่าระยะหมดเวลาเซสชัน

เวอร์ชันที่รองรับ

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.0.0

นิยามอินเทอร์เฟซ

• + (void)setNoActiveSessionEndDurationTime:(NSInteger)interval;
  • คำอธิบายอินเทอร์เฟซ:
    • ตั้งค่าระยะหมดเวลาเซสชัน ค่าเริ่มต้นคือ 30 นาที
    • เมื่อแอปเข้าสู่เบื้องหลัง ระบบเริ่มจับเวลาหมดอายุเซสชัน หากไม่มีกิจกรรมภายในช่วงเวลานั้น เซสชันปัจจุบันจะสิ้นสุด
  • พารามิเตอร์
    • interval: ระยะหมดเวลา หน่วย s (วินาที)

ตัวอย่างการเรียกใช้

              
                  [MTMAService setNoActiveSessionEndDurationTime:50];

            

รับ EUID

เวอร์ชันที่รองรับ

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.0.0

นิยามอินเทอร์เฟซ

• + (nullable NSString * )EUID;
  • คำอธิบายอินเทอร์เฟซ:
    • รับ EUID ของ EngageLab MA
    • คืนค่า nil หาก SDK ยังเริ่มต้นใช้งานไม่สำเร็จ

ตัวอย่างการเรียกใช้

              
                  [MTMAService EUID];

            

ตั้งค่าคุณสมบัติ UTM

เวอร์ชันที่รองรับ

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.0.0

นิยามอินเทอร์เฟซ

• + (void)setUtmProperties:(NSDictionary * )property;
  • คำอธิบายอินเทอร์เฟซ:
    • คุณสมบัติ UTM เป็นคุณสมบัติเหตุการณ์มาตรฐาน หากระบุได้ว่าผู้ใช้เข้าถึงแอปจากโฆษณาใด แนะนำให้ตั้งค่าข้อมูล UTM ซึ่งจะส่งไปพร้อมการรายงานเหตุการณ์ คุณสมบัติที่ตั้งค่าได้มีดังนี้:
      • utm_source: แหล่งที่มาของแคมเปญ
      • utm_medium: สื่อของแคมเปญ
      • utm_term: คำค้นของแคมเปญ
      • utm_content: เนื้อหาของแคมเปญ
      • utm_campaign: ชื่อแคมเปญ
      • utm_id: ID แคมเปญ

ตัวอย่างการเรียกใช้

              
                  [MTMAService setUtmProperties:@{@"utm_source":@"value"}];

            

ตั้งค่าคุณสมบัติผู้ใช้

เขียนทับและอัปเดตคุณสมบัติผู้ใช้

• + (void)setProperty:(NSDictionary * )userinfo completion:(void (^)(NSInteger code, NSString * message))completion;
  • คำอธิบายอินเทอร์เฟซ:
    • ตั้งค่าคุณสมบัติผู้ใช้เป็นชุดได้สูงสุด 100 รายการต่อครั้ง หากคุณสมบัติใดไม่ผ่านการตรวจสอบของ SDK ระบบจะไม่ส่งคำขอทั้งชุด
    • ชื่อคุณสมบัติต้องเป็น NSString เริ่มด้วยตัวอักษรพิมพ์เล็ก มีได้เฉพาะตัวอักษรพิมพ์เล็ก ตัวเลข และขีดล่าง ยาวไม่เกิน 50 ไบต์ UTF-8 และห้ามขึ้นต้นด้วย el, engagelab หรือ metaverse
    • Value รองรับ NSString, NSNumber ที่มีค่าจำกัด (finite), NSSet/NSArray ของสตริง, NSDictionary (object) และ NSArray<NSDictionary *> (object_array)
    • คุณสมบัติชนิดทั่วไปจะถูกเขียนทับหากมีอยู่แล้ว หรือสร้างใหม่หากยังไม่มี ส่วน object จะผสานฟิลด์ย่อย และ object_array จะแทนที่ทั้งอาร์เรย์โดยรักษาลำดับอาร์เรย์
  • ตัวอย่างการเรียกใช้:

              
                 [MTMAService setProperty:@{
       @"level": @"gold",
       @"profile": @{ @"city": @"Singapore", @"score": @100 },
       @"addresses": @[
           @{ @"id": @"home", @"city": @"Singapore" },
           @{ @"id": @"office", @"city": @"Tokyo" }
       ]
   } completion:^(NSInteger code, NSString * _Nonnull message) {
       // code == 0 หมายถึงเซิร์ฟเวอร์ประมวลผลคำขอสำเร็จ
   }];

            

• + (void)setProperty:(NSString * )key to:(id)value completion:(void (^)(NSInteger code, NSString * message))completion;
  • คำอธิบายอินเทอร์เฟซ:
    • ตั้งค่าเนื้อหาของคุณสมบัติผู้ใช้หนึ่งรายการ
    • กฎชื่อคุณสมบัติ ชนิด Value และพฤติกรรมการอัปเดตเหมือนกับอินเทอร์เฟซแบบชุดทุกประการ
  • ตัวอย่างการเรียกใช้:

              
                 [MTMAService setProperty:@"profile"
                         to:@{ @"city": @"Singapore", @"score": @100 }
                 completion:^(NSInteger code, NSString * _Nonnull message) {
   }];

            

กฎของ object / object_array

• object ต้องเป็น NSDictionary ที่ไม่ว่าง ชื่อฟิลด์ย่อยต้องเป็น NSString ที่ไม่ว่างและห้ามมี . หรือ $
• ค่าฟิลด์ย่อยของ object รองรับ NSString, NSNumber ที่มีค่าจำกัด (finite), NSSet/NSArray ของสตริง และ NSNull ไม่รองรับ object หรือ object_array ที่ซ้อนอยู่ภายใน
• เมื่อเรียก setProperty กับ object อีกครั้ง จะผสานเฉพาะฟิลด์ย่อยที่ส่งมาครั้งนี้ ฟิลด์ที่ไม่ได้ส่งจะคงเดิม การส่งค่า NSNull หมายถึงลบฟิลด์ย่อยนั้น
• object_array ต้องเป็น NSArray<NSDictionary *> โดยแต่ละออบเจ็กต์ต้องไม่ว่างและเป็นไปตามกฎฟิลด์ย่อยเดียวกัน การเรียก setProperty อีกครั้งจะแทนที่ทั้งอาร์เรย์
• แต่ละสมาชิกของ object_array ต้องเหลือฟิลด์ย่อยที่มีค่าไม่ใช่ NSNull อย่างน้อยหนึ่งฟิลด์ ห้ามส่งออบเจ็กต์ที่ค่าฟิลด์ย่อยทั้งหมดเป็น NSNull
• อาร์เรย์ว่างใช้ล้างคุณสมบัติอาร์เรย์ที่มีอยู่แล้วได้ แต่ในการสร้างครั้งแรก อาร์เรย์ว่างอย่างเดียวไม่สามารถแยกได้ว่าเป็นรายการสตริงหรือ object_array หากสร้าง object_array ครั้งแรก ให้ส่งอาร์เรย์ออบเจ็กต์ที่ไม่ว่าง
• ใช้ NSNull ได้เฉพาะเป็นค่าฟิลด์ย่อยของ object/object_array ไม่สามารถใช้ NSNull ระดับบนสุดเพื่อลบคุณสมบัติทั้งหมดได้ หากต้องการลบทั้งคุณสมบัติ ให้เรียก deleteProperty:completion:

ตัวอย่างการอัปเดต object บางส่วนและลบฟิลด์ย่อย:

              
              // อัปเดตเฉพาะ profile.score โดย profile.city คงเดิม
[MTMAService setProperty:@"profile"
                      to:@{ @"score": @200 }
              completion:completion];

// ลบเฉพาะ profile.city
[MTMAService setProperty:@"profile"
                      to:@{ @"city": NSNull.null }
              completion:completion];

            

อัปเดตสมาชิก object_array บางส่วน

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.5.0

• **+ (void)updateObjectArrayProperty:(NSString *)key identifierKey:(NSString )identifierKey identifierValue:(id)identifierValue values:(NSDictionary<NSString *, id> )values completion:(void (^)(NSInteger code, NSString * message))completion;
  • คำอธิบายอินเทอร์เฟซ:
    • ค้นหาออบเจ็กต์ใน object_array ด้วยฟิลด์ย่อยที่ระบุได้เพียงรายการเดียว แล้วผสานฟิลด์ย่อยใน values
    • ฟิลด์ย่อยที่ identifierKey ระบุต้องกำหนดไว้ในเมทาดาทาของเซิร์ฟเวอร์แล้ว และเป็นชนิด string หรือ number เท่านั้น identifierValue ต้องเป็นชนิดเดียวกัน คือ NSString หรือ NSNumber ที่ไม่ใช่บูลีนและมีค่า finite โดยต้องตรงกับสมาชิกในอาร์เรย์ปัจจุบันเพียงหนึ่งรายการ
    • values ต้องเป็นดิกชันนารีที่ไม่ว่าง ห้ามมี identifierKey และห้ามซ้อน object/object_array ฟิลด์ที่ไม่ได้ส่งจะคงเดิม การส่งค่า NSNull จะลบฟิลด์ย่อยนั้น
    • คุณสมบัตินี้ต้องกำหนดเป็น object_array ในเมทาดาทาของเซิร์ฟเวอร์แล้ว และผู้ใช้ปัจจุบันต้องมีค่าคุณสมบัตินี้อยู่แล้ว สำหรับการสร้างครั้งแรก ใช้ setProperty:to: พร้อมอาร์เรย์ออบเจ็กต์ที่ไม่ว่าง
    • หากยังไม่ได้กำหนดคุณสมบัติ หรือกำหนดแล้วแต่ผู้ใช้ปัจจุบันยังไม่มีค่า เซิร์ฟเวอร์จะคืน code=0 โดยไม่แก้ไขข้อมูล code=0 หมายถึงประมวลผลคำขอสำเร็จเท่านั้น ควรตรวจสอบผลการแก้ไขจริงผ่านคอนโซล MA หรือคุณสมบัติผู้ใช้บนเซิร์ฟเวอร์
    • หากมีอาร์เรย์อยู่แล้วแต่ไม่พบรายการที่ตรงกัน พบหลายรายการ ชนิดฟิลด์ตัวระบุไม่ตรงกัน หรือฟิลด์ย่อยไม่เป็นไปตามเมทาดาทา เซิร์ฟเวอร์จะคืนรหัสความล้มเหลว โดยไม่สร้างหรือแก้ไขสมาชิกอื่น
  • ตัวอย่างการเรียกใช้:

              
              // ออบเจ็กต์ที่ id == home: เปลี่ยน city เป็น Tokyo และลบ zip
[MTMAService updateObjectArrayProperty:@"addresses"
                         identifierKey:@"id"
                       identifierValue:@"home"
                                values:@{
                                    @"city": @"Tokyo",
                                    @"zip": NSNull.null
                                }
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

เพิ่มสมาชิก object_array

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.5.0

• **+ (void)addObjectArrayProperty:(NSString )key object:(NSDictionary<NSString *, id> )object completion:(void (^)(NSInteger code, NSString * message))completion;
  • คำอธิบายอินเทอร์เฟซ:
    • เพิ่มออบเจ็กต์ หนึ่งรายการ ที่ท้าย object_array โดยไม่กระทบสมาชิกเดิม แตกต่างจากการส่งทั้งอาร์เรย์ให้ setProperty:to: ซึ่งจะแทนที่อาร์เรย์ทั้งหมด
    • object ต้องเป็น NSDictionary ที่ไม่ว่าง และต้องเหลือฟิลด์ย่อยที่มีค่าไม่ใช่ NSNull อย่างน้อยหนึ่งฟิลด์ ใช้กฎฟิลด์ย่อยเดียวกับ object และไม่รองรับ object/object_array ที่ซ้อนอยู่ภายใน
    • คุณสมบัตินี้ต้องกำหนดเป็น object_array ในเมทาดาทาของเซิร์ฟเวอร์แล้ว หากยังไม่ได้กำหนด เซิร์ฟเวอร์จะคืน code=0 โดยไม่แก้ไขข้อมูล ให้สร้างครั้งแรกด้วย setProperty:to: และอาร์เรย์ออบเจ็กต์ที่ไม่ว่างก่อน
    • หากกำหนดคุณสมบัติแล้วแต่ผู้ใช้ปัจจุบันยังไม่มีค่า อินเทอร์เฟซนี้จะสร้างอาร์เรย์ที่มีสมาชิกหนึ่งรายการนี้
  • ตัวอย่างการเรียกใช้:

              
              [MTMAService addObjectArrayProperty:@"addresses"
                                object:@{
                                    @"id": @"school",
                                    @"city": @"Osaka"
                                }
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

ลบสมาชิก object_array

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.5.0

• **+ (void)removeObjectArrayProperty:(NSString )key identifierKey:(NSString )identifierKey identifierValue:(id)identifierValue completion:(void (^)(NSInteger code, NSString * message))completion;
  • คำอธิบายอินเทอร์เฟซ:
    • ค้นหาและลบ สมาชิกทั้งรายการในอาร์เรย์ ด้วยฟิลด์ย่อยที่ระบุได้เพียงรายการเดียว หากต้องการลบเฉพาะฟิลด์ย่อยภายในสมาชิก ให้ใช้ updateObjectArrayProperty: และส่ง NSNull ให้ฟิลด์นั้น
    • ข้อจำกัดของ identifierKey / identifierValue เหมือนกับ updateObjectArrayProperty: ทุกประการ: ฟิลด์ย่อยต้องกำหนดไว้ในเมทาดาทาแล้ว เป็นชนิด string หรือ number เท่านั้น และต้องตรงกับสมาชิกในอาร์เรย์ปัจจุบันเพียงหนึ่งรายการ
    • หากคุณสมบัติยังไม่ได้กำหนดบนเซิร์ฟเวอร์ ผู้ใช้ปัจจุบันไม่มีค่าคุณสมบัตินี้ หรือไม่พบรายการที่ตรงกัน เซิร์ฟเวอร์จะข้ามคำขอและคืน code=0 ต้องตรวจสอบผลการแก้ไขจริงผ่านคอนโซล MA หรือคุณสมบัติผู้ใช้บนเซิร์ฟเวอร์
    • หากพบหลายรายการที่ตรงกันหรือชนิดฟิลด์ตัวระบุไม่ตรงกัน เซิร์ฟเวอร์จะคืนรหัสความล้มเหลว โดยไม่ลบสมาชิกอื่นผิดรายการ
  • ตัวอย่างการเรียกใช้:

              
              // ลบที่อยู่ที่ id == office
[MTMAService removeObjectArrayProperty:@"addresses"
                         identifierKey:@"id"
                       identifierValue:@"office"
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

เพิ่มค่าคุณสมบัติผู้ใช้แบบสะสม

• **+ (void)increaseProperty:(NSString )key by:(NSNumber )amount completion:(void (^)(NSInteger code, NSString * message))completion;
  • คำอธิบายอินเทอร์เฟซ:
    • เพิ่มค่าให้คุณสมบัติผู้ใช้ชนิดตัวเลขหนึ่งรายการ เพื่อสะสมข้อมูลที่รายงานทั้งหมด เช่น ยอดใช้จ่ายสะสม
    • ใช้ได้เฉพาะกับคุณสมบัติชนิด NSNumber เท่านั้น มิฉะนั้นจะข้ามการทำงาน หากยังไม่มีคุณสมบัตินี้ จะถือว่าค่าเริ่มต้นเป็น 0
  • ตัวอย่างการเรียกใช้:

              
                  [MTMAService increaseProperty:@"key" by:@(2) completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

• **+ (void)increaseProperty:(NSDictionary )userinfo completion:(void (^)(NSInteger code, NSString * message))completion;*
  • คำอธิบายอินเทอร์เฟซ:
    • เพิ่มค่าให้คุณสมบัติผู้ใช้ชนิดตัวเลขหลายรายการ เพื่อสะสมข้อมูลที่รายงานทั้งหมด เช่น ยอดใช้จ่ายสะสม
    • ใช้ได้เฉพาะกับคุณสมบัติชนิด NSNumber เท่านั้น มิฉะนั้นจะข้ามการทำงาน หากยังไม่มีคุณสมบัตินี้ จะถือว่าค่าเริ่มต้นเป็น 0
  • ตัวอย่างการเรียกใช้:

              
                  [MTMAService increaseProperty:@{@"key1":@(5),@"key2":@(3)} completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

เพิ่มค่าในคุณสมบัติผู้ใช้

• **+ (void)addProperty:(NSString )key by:(NSObject )content completion:(void (^)(NSInteger code, NSString * message))completion
  • คำอธิบายอินเทอร์เฟซ:
    • เพิ่มค่าบางรายการในคุณสมบัติชนิด NSSet หรือ NSArray หนึ่งรายการ
    • สมาชิกของ NSSet หรือ NSArray ต้องเป็น NSString มิฉะนั้นจะข้ามการทำงาน หากคุณสมบัติที่จะเพิ่มค่ายังไม่มีอยู่ จะเริ่มต้นด้วย NSSet หรือ NSArray ว่าง
  • ตัวอย่างการเรียกใช้:

              
                  [MTMAService addProperty:@"key" by:@[@"value"] completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

• **+ (void)addProperty:(NSDictionary )userinfo completion:(void (^)(NSInteger, NSString * _Nonnull))completion;*
  • คำอธิบายอินเทอร์เฟซ:
    • เพิ่มค่าบางรายการในคุณสมบัติชนิด NSSet หรือ NSArray หลายรายการ
    • สมาชิกของ NSSet หรือ NSArray ต้องเป็น NSString มิฉะนั้นจะข้ามการทำงาน หากคุณสมบัติที่จะเพิ่มค่ายังไม่มีอยู่ จะเริ่มต้นด้วย NSSet หรือ NSArray ว่าง
  • ตัวอย่างการเรียกใช้:

              
                  [MTMAService addProperty:@{@"key1":@[@"value"],@"key2":@[@"value"]} completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

ลบค่าออกจากคุณสมบัติผู้ใช้

• **+ (void)removeProperty:(NSString * )key by:(NSObject )content completion:(void (^)(NSInteger code, NSString * message))completion;*
  • คำอธิบายอินเทอร์เฟซ:
    • ลบค่าบางรายการออกจากคุณสมบัติชนิด NSSet หรือ NSArray หนึ่งรายการ
    • content ต้องเป็น NSSet หรือ NSArray ที่มีสมาชิกเป็น NSString
  • ตัวอย่างการเรียกใช้:

              
                  [MTMAService removeProperty:@"key" by:@[@"value"] completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

ลบคุณสมบัติผู้ใช้

เวอร์ชันที่รองรับ

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.0.0

นิยามอินเทอร์เฟซ

• + (void)deleteProperty:(NSString * )key completion:(void (^)(NSInteger code, NSString * message))completion;
  • คำอธิบายอินเทอร์เฟซ:
    • ลบเนื้อหาทั้งหมดของคุณสมบัติผู้ใช้หนึ่งรายการ ใช้ได้กับชนิดทั่วไป object และ object_array
    • หากยังไม่มีคุณสมบัตินี้ จะข้ามการทำงาน

ตัวอย่างการเรียกใช้

              
                  [MTMAService deleteProperty:@"key" completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

ควบคุมการเก็บข้อมูล

เวอร์ชันที่รองรับ

เริ่มรองรับตั้งแต่เวอร์ชัน: 5.0.0

นิยามอินเทอร์เฟซ

• **+ (void)setCollectControl:(MTMACollectControl )control;*
  • คำอธิบายอินเทอร์เฟซ:
    • ควบคุมว่าจะเก็บรายการข้อมูลในคลาส MTMACollectControl หรือไม่

ตัวอย่างการเรียกใช้

              
                  MTMACollectControl *collectControl = [[MTMACollectControl alloc] init];
    collectControl.idfa = YES;
    collectControl.idfv = YES;
    collectControl.carrier = YES;
    [MTMAService setCollectControl:collectControl];

            

คลาส MTMAConfig

คลาสข้อมูลการกำหนดค่าแอป มีคุณสมบัติดังนี้:

คลาส MTMAInitResult

ออบเจ็กต์ผลการเริ่มต้นใช้งาน SDK ที่ resultCompletion คืนให้ ไม่ต้องสร้างหรือเรียกแยกต่างหาก มีคุณสมบัติดังนี้:

คลาส MTMAUserID

โมเดลตัวระบุผู้ใช้ ส่งผ่าน MTMAConfig.userID ระหว่างการเริ่มต้นใช้งาน และผ่าน identifyAccount: ระหว่างการทำงาน

ตัวระบุทั้งสี่เป็นฟิลด์ที่ไม่บังคับ ระบบจะตัดช่องว่างต้นและท้าย ค่าว่างและ 0/null/undefined/nan (ไม่แยกตัวพิมพ์เล็กและใหญ่) จะถือว่าไม่ได้ส่ง ไม่ใช้ในการจับคู่ และไม่สร้างผลรายฟิลด์ ข้อจำกัดต่อไปนี้ใช้กับค่าที่เหลือหลังการปรับข้อมูลดังกล่าว:

ฟิลด์ที่ไม่ใช่ NSString หรือมีรูปแบบไม่ถูกต้องจะถูกตัดออกและบันทึกผลเป็น 3013 ส่วนฟิลด์ที่ยาวเกินกำหนดจะเป็น 3003 ฟิลด์ที่ถูกต้องอื่นยังคงถูกส่ง หากไม่มีฟิลด์ที่ถูกต้อง การเริ่มต้นใช้งานจะดำเนินต่อเหมือนไม่ได้ส่งตัวตน ส่วน identifyAccount: จะคืน -3 โดยไม่ส่งคำขอ SDK ไม่แก้ไขออบเจ็กต์ของผู้เรียก และเซิร์ฟเวอร์จะเปลี่ยน email เป็นตัวพิมพ์เล็ก

เมื่อเริ่มต้นใช้งานสำเร็จ userID.completion จะคืน code=0 โดย message เป็นสตริงว่างหรือ JSON ที่มีเฉพาะฟิลด์ที่ถูกปฏิเสธภายใน SDK ไม่รวมผลรายฟิลด์จากเซิร์ฟเวอร์ จึงไม่สามารถสรุปว่าผูกตัวระบุทั้งหมดแล้ว ให้ยึด config.resultCompletion เป็นผลการเริ่มต้นใช้งาน SDK ซึ่ง callback นี้ไม่มี JSON รายตัวระบุ ดู callback ระหว่างการทำงานใน ตั้งค่าตัวระบุผู้ใช้

คลาส MTMACollectControl

โมเดลควบคุมการเก็บข้อมูลผู้ใช้ มีคุณสมบัติดังนี้:

คลาส MTMAUserContact

โมเดลช่องทางติดต่อผู้ใช้ มีคุณสมบัติดังต่อไปนี้:
หากไม่ได้ตั้งค่าหรือกำหนดเป็น nil จะไม่แก้ไขข้อมูล การตั้งเป็นสตริงว่าง "" หมายถึงล้างข้อมูลติดต่อนั้น สตริงที่ไม่ว่างแต่มีเฉพาะอักขระเว้นวรรคถือว่าไม่ถูกต้อง

คลาส MTMAEventObject

คลาสออบเจ็กต์เหตุการณ์ที่กำหนดเอง มีคุณสมบัติดังนี้: