คู่มือ SDK API

              
              # iOS SDK API

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

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

## เริ่มต้นฟังก์ชัน MA

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

เวอร์ชันที่เริ่มรองรับ: 5.0.0

#### การกำหนดอินเตอร์เฟซ

- **+ start:(MTMAConfig * )config;** 
   - คำอธิบายอินเตอร์เฟซ: 
      - เปิดใช้งานฟังก์ชัน EngageLab MA
      - อินเตอร์เฟซ start เป็นอินเตอร์เฟซเริ่มต้นสำหรับอินเตอร์เฟซอื่น ๆ ดังนั้นต้องเรียกใช้อินเตอร์เฟซ start ก่อนจึงจะสามารถเรียกใช้อินเตอร์เฟซอื่นได้
   - คำอธิบายพารามิเตอร์ 
      - config คลาสการตั้งค่า

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

            

              
              MTMAConfig *config = [[MTMAConfig alloc] init];
[MTMAService start:config];

            

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

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

เวอร์ชันที่เริ่มรองรับ: 5.0.0

#### การกำหนดอินเตอร์เฟซ

- **+ (void)setUserContact:(MTMAUserContact * )contact;** 
   - คำอธิบายอินเตอร์เฟซ: 
      - ตั้งค่าข้อมูลการติดต่อผู้ใช้งาน
   - คำอธิบายพารามิเตอร์ 
      - contacts: ตั้งค่าข้อมูลการติดต่อหลายรายการ คีย์คือชื่อของข้อมูลการติดต่อ และค่าคือค่าของข้อมูลการติดต่อ ขณะนี้รองรับข้อมูลการติดต่อ 4 ประเภท: email, mobile_phone, landline_phone และ whatsapp_phone

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

            

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

            

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

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

เวอร์ชันที่เริ่มรองรับ: 5.0.0

#### การกำหนดอินเตอร์เฟซ

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

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

            

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

            

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

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

เวอร์ชันที่เริ่มรองรับ: 5.0.0

#### การกำหนดอินเตอร์เฟซ

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

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

            

              
              MTMAUserID *userid = [[MTMAUserID alloc] init];
userid.anonymousID = @"xxx";
userid.userID = @"xxx";
[MTMAService identifyAccount:userid];

            

              
              
## ตั้งค่าช่วงเวลาการรายงานข้อมูลที่อัปโหลด

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

เวอร์ชันที่เริ่มรองรับ: 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

#### การกำหนดอินเตอร์เฟซ

- **+ (NSString * )EUID;** 
   - คำอธิบายอินเตอร์เฟซ: 
      - รับค่า EUID ของ EngageLab MA

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

            

              
              [MTMAService EUID];

            

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

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

เวอร์ชันที่เริ่มรองรับ: 5.0.0

#### การกำหนดอินเตอร์เฟซ

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

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

            

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

            

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

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

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

            

              
              
- **+ (void)setProperty:(NSString * )key to:(id)value completion:(void (^)(NSInteger code, NSString * message))completion;** 
   - คำอธิบายอินเทอร์เฟซ: 
      - ตั้งค่าเนื้อหาของคุณสมบัติผู้ใช้เดี่ยวของผู้ใช้
      - เนื้อหาของคุณสมบัติผู้ใช้เหล่านี้ถูกเก็บไว้ใน NSDictionary โดยที่ key คือชื่อของคุณสมบัติผู้ใช้และต้องเป็น NSString และ value คือเนื้อหาของคุณสมบัติผู้ใช้ซึ่งรองรับเฉพาะประเภท NSString, NSNumber, NSSet และ NSArray
      - ปัจจุบัน องค์ประกอบใน value ของประเภท NSSet หรือ NSArray รองรับเฉพาะการเป็น NSString
      - หากคุณสมบัติผู้ใช้บางอย่างมีอยู่ก่อนแล้ว จะถูกเขียนทับในครั้งนี้; หากไม่มีอยู่ จะถูกสร้างขึ้น ตัวอย่างเช่น ระดับสมาชิกของผู้ใช้
   - ตัวอย่างการเรียกใช้:

            

              
              
### เพิ่มและอัปเดตคุณสมบัติผู้ใช้

- **+ (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<NSFastEnumeration> *)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<NSFastEnumeration> *)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;** 
   - คำอธิบายอินเทอร์เฟซ: 
      - ลบเนื้อหาทั้งหมดของคุณสมบัติผู้ใช้บางอย่าง
      - หากคุณสมบัติผู้ใช้นี้ไม่มีอยู่ก่อน จะถูกละเว้นโดยตรง

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

            

              
              [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

คลาสข้อมูลการกำหนดค่าของแอปพลิเคชัน ต่อไปนี้คือคำอธิบายของคุณสมบัติ:

| ชื่อพารามิเตอร์ | ประเภทพารามิเตอร์ | คำอธิบายพารามิเตอร์ |
| --- | --- | --- |
| userID | MTMAUserID | โมเดลการระบุผู้ใช้ เมื่อกำหนดคุณสมบัตินี้ การระบุผู้ใช้จะถูกตั้งค่าในระหว่างการเริ่มต้นใช้งาน |
| completion | (^)(NSInteger code, NSString * message) | การเรียกกลับผลลัพธ์ของคำขอ โดยที่ code: 0 หมายถึงสำเร็จ |


## คลาส MTMAUserID

โมเดลการระบุผู้ใช้ ต่อไปนี้คือคำอธิบายของคุณสมบัติ:

| ชื่อพารามิเตอร์ | ประเภทพารามิเตอร์ | คำอธิบายพารามิเตอร์ |
| --- | --- | --- |
| userID | NSString | ตั้งค่าการระบุผู้ใช้ที่เข้าสู่ระบบที่ไม่ซ้ำกันที่นี่ |
| anonymousID | NSString | เมื่อผู้ใช้ไม่ได้เข้าสู่ระบบแต่มีการให้ข้อมูลที่สามารถระบุได้ สามารถตั้งค่าเป็น ID นิรนาม เช่น ที่อยู่อีเมลหรือ ID ที่สร้างโดยบุคคลที่สาม |
| completion | (^)(NSInteger code, NSString * message) | การเรียกกลับผลลัพธ์ของคำขอ โดยที่ code: 0 หมายถึงสำเร็จ |


## คลาส MTMACollectControl

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

| ชื่อพารามิเตอร์ | ประเภทพารามิเตอร์ | คำอธิบายพารามิเตอร์ |
| --- | --- | --- |
| idfa | BOOL | จะเก็บข้อมูล idfa หรือไม่ ตั้งค่าเป็น NO เพื่อไม่เก็บข้อมูล idfa ค่าเริ่มต้นคือ NO |
| idfv | BOOL | จะเก็บข้อมูล idfv หรือไม่ ตั้งค่าเป็น NO เพื่อไม่เก็บข้อมูล idfv ค่าเริ่มต้นคือ NO |
| carrier | BOOL | จะเก็บข้อมูลผู้ให้บริการหรือไม่ ตั้งค่าเป็น NO เพื่อไม่เก็บข้อมูลผู้ให้บริการ ค่าเริ่มต้นคือ YES |


## คลาส MTMAUserContact

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

| ชื่อพารามิเตอร์ | ประเภทพารามิเตอร์ | คำอธิบายพารามิเตอร์ |
| --- | --- | --- |
| contacts | NSDictionary | พจนานุกรมข้อมูลการติดต่อ รองรับ 4 ประเภทของข้อมูลการติดต่อ: email, mobile_phone, landline_phone และ whatsapp_phone |
| completion | (^)(NSInteger code, NSString * message) | การเรียกกลับผลลัพธ์ของคำขอ โดยที่ code: 0 หมายถึงสำเร็จ |


## คลาส MTMAEventObject

คลาสวัตถุเหตุการณ์ที่กำหนดเอง ต่อไปนี้คือคำอธิบายของคุณสมบัติ:

| ชื่อพารามิเตอร์ | ประเภทพารามิเตอร์ | คำอธิบายพารามิเตอร์ |
| --- | --- | --- |
| eventName | NSString | รหัสเหตุการณ์ ซึ่งจำเป็นและต้องไม่ว่างเปล่า |
| property | NSDictionary<NSString *, id> | คุณสมบัติที่กำหนดเอง (น้อยกว่าหรือเท่ากับ 500) key เป็น NSString และสามารถมีเฉพาะตัวเลข ตัวอักษร และขีดล่าง; value สามารถเป็น NSString/NSNumber |