คู่มือการรวมฟังก์ชัน Android MA

รุ่นที่ใช้งานได้

บทความนี้ใช้กับ MA SDK เวอร์ชันอิสระของ 5.5.0 และเวอร์ชันที่ใหม่กว่า

ตั้งแต่เวอร์ชัน 5.5.0 เป็นต้นไป MA จะไม่อาศัย AppPush อีกต่อไป และสามารถรวมและเริ่มต้นได้อย่างอิสระ MA AppKey และ Push AppKey มีความเป็นอิสระจากกันและอาจเหมือนกันหรือต่างกันก็ได้

สำหรับวิธีการผสานรวมของ Fusion เวอร์ชันก่อน 5.5.0 โปรดดู คู่มือการประกอบรวมก่อน 5.5.0

1. นำเข้า SDK

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

เพิ่ม mt-sdk-ma-5.5.0.aar ในแพ็คเกจ release ไปยังไดเร็กทอรี libs ของโปรเจ็กต์แอปพลิเคชัน:

              
              dependencies {
    implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
}

            

มาเวนนำเข้า

              
              dependencies {
    implementation 'com.engagelab.plugin:oth_ma:5.5.0'
}

            

หากคุณใช้ AppPush ในเวลาเดียวกัน ให้ปฏิบัติตามเอกสาร AppPush เพื่อแนะนำแพ็คเกจหลัก engagelab เมื่อใช้ MA เท่านั้น คุณไม่จำเป็นต้องแนะนำแพ็คเกจหลักของ AppPush

2. การกำหนดค่าการอนุญาต

ประกาศการอนุญาตเครือข่ายใน AndroidManifest.xml:

              
              <uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

            

MA เวอร์ชันสแตนด์อโลนไม่ต้องการการกำหนดค่าของ ENGAGELAB_PRIVATES_APPKEY, ENGAGELAB_PRIVATES_CHANNEL, Push Service หรือ Push Receiver หากคุณใช้ AppPush ในเวลาเดียวกัน คุณยังคงต้องดำเนินการกำหนดค่าที่เกี่ยวข้องให้เสร็จสิ้นตามเอกสารการรวม AppPush

3. เริ่มต้น SDK

ขอแนะนำให้เริ่มต้นใน Application.onCreate() ของกระบวนการหลัก MA AppKey ใช้สำหรับการเริ่มต้น และไม่จำเป็นต้องรอการเริ่มต้น AppPush หรือการลงทะเบียนสำเร็จ

              
              import android.app.Application;

import com.engagelab.privates.push.oth.ma.api.MTMAApi;
import com.engagelab.privates.push.oth.ma.api.MTMAConfig;
import com.engagelab.privates.push.oth.ma.api.MTMAInitResult;
import com.engagelab.privates.push.oth.ma.api.MTMAInitResultCallback;

public class MainApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        MTMAApi.configDebugMode(true);
        MTMAConfig config = new MTMAConfig("your MA AppKey");
        MTMAApi.getInstance(this).start(config, new MTMAInitResultCallback() {
            @Override
            public void onResult(MTMAInitResult result) {
                if (result.isSuccess()) {
                    String euid = result.getEuid();
                    String maRid = result.getMaRid();
                } else {
                    int code = result.getCode();
                    String message = result.getMessage();
                }
            }
        });
    }
}

            

คำแนะนำในการเริ่มต้น

• ต้องมี MA AppKey
• Android MA SDK รองรับการเริ่มต้นในกระบวนการหลักของแอปพลิเคชันโฮสต์เท่านั้น การเรียก start ในกระบวนการที่ไม่ใช่กระบวนการหลักจะส่งคืนความล้มเหลวผ่านการเรียกกลับ และจะไม่มีการเริ่มต้นคำขอเครือข่าย
• ก่อนที่การกำหนดค่าเริ่มต้นจะสำเร็จ API ธุรกิจ MA อื่นๆ จะไม่สามารถใช้งานได้ยกเว้นอินเทอร์เฟซการกำหนดค่าล่วงหน้า
• ขอแนะนำให้เรียกใช้ API ภายนอก MA ทั้งหมดในกระบวนการหลัก กระบวนการที่ไม่ใช่กระบวนการหลักจะไม่แชร์สถานะการเริ่มต้นของกระบวนการหลัก และการเรียกทางธุรกิจจะไม่ถูกส่งต่อไปยังกระบวนการหลัก
• หลังจากการกำหนดค่าเริ่มต้นสำเร็จแล้ว ยังสามารถรับค่าปัจจุบันผ่าน getEuid() และ getMaRid() ได้อีกด้วย

สลับ MA AppKey เมื่อรันไทม์

กระบวนการเดียวกันนี้รองรับการสลับ MA AppKey เมื่อรันไทม์ โปรดโทรไปที่ start อีกครั้งด้วย AppKey ใหม่ หลังจากการเรียกกลับการกำหนดค่าเริ่มต้นครั้งล่าสุดเสร็จสิ้น

              
              MTMAConfig newConfig = new MTMAConfig("new MA AppKey");
MTMAApi.getInstance(this).start(newConfig, callback);

            

ในระหว่างการเปลี่ยน API ธุรกิจ MA อื่นๆ จะไม่สามารถใช้งานได้ชั่วคราว หลังจากเริ่มต้น AppKey ใหม่สำเร็จแล้ว เหตุการณ์ต่อมาและข้อมูลผู้ใช้จะเป็นของ AppKey ใหม่ หาก AppKey ใหม่ไม่สามารถเริ่มต้นได้ SDK จะไม่ถอยกลับไปเป็น AppKey เก่าโดยอัตโนมัติ และจะต้องเรียก start อีกครั้งด้วย AppKey ที่ถูกต้อง

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

              
              UserIdentity identity = new UserIdentity();
identity.setUserId("your user id");
identity.setAnonymousId("your anonymous id");
identity.setEmail("user@example.com");
identity.setPhone("+8613800138000");

MTMAConfig config = new MTMAConfig("your MA AppKey", identity);
MTMAApi.getInstance(this).start(config, callback);

            

ในจำนวนนี้ รองรับ setEmail และ setPhone ตั้งแต่เวอร์ชัน 5.5.0

กฎของฟิลด์ข้อมูลระบุตัวตนผู้ใช้: หลังตัดช่องว่างหน้าและหลังแล้ว user_id ต้องไม่ว่าง มีความยาวไม่เกิน 255 อักขระ Unicode และต้องไม่เท่ากับ 0, null, undefined หรือ nan (ไม่คำนึงถึงตัวพิมพ์เล็ก/ใหญ่) หลังตัดช่องว่างแล้ว anonymous_id ต้องไม่ว่างและมีความยาวไม่เกิน 256 อักขระ Unicode email ต้องไม่ว่าง มีความยาวไม่เกิน 256 อักขระ Unicode ต้องมี @ เพียงหนึ่งตัว โดยข้อความทั้งสองด้านต้องไม่ว่าง และต้องไม่มีช่องว่าง การขึ้นบรรทัดใหม่ หรือแท็บ phone ต้องใช้รูปแบบ E.164: ขึ้นต้นด้วย + รหัสประเทศขึ้นต้นด้วยตัวเลข 1–9 และตามด้วยตัวเลข 1–14 หลัก หากตรวจสอบไม่ผ่าน SDK จะไม่ส่งคำขอข้อมูลระบุตัวตน และจะส่งคืน code = -3 ผ่าน callback

4. ใช้ AppPush พร้อมกัน

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

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

AppPush ไม่ได้รวมเข้าด้วยกัน ไม่ได้ลงทะเบียน หรือการเชื่อมโยงช่องสัญญาณล้มเหลว ซึ่งไม่ส่งผลต่อการเริ่มต้น MA การรวบรวมเหตุการณ์ และการรายงาน

หมายเหตุ: MA RID และ AppPush RID เป็นตัวระบุอุปกรณ์สองตัวที่เป็นอิสระ โปรดรับและใช้งานผ่าน SDK ที่เกี่ยวข้องตามลำดับ อย่าใช้อันหนึ่งเป็นอันอื่น

5. ตั้งค่า ID ผู้ติดต่อของช่อง

หากคุณต้องการตั้งค่า ID ผู้ติดต่อของช่องสำหรับช่อง Push ของบุคคลที่สาม โปรดโทรหลังจากเริ่มต้น MA สำเร็จแล้ว:

              
              List<String> values = Collections.singletonList("push rid or token");
MTMAApi.getInstance(this).setChannelValue(136L, values, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
        // code == 0 means success
    }
});

            

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

6. คำแนะนำในการอัพเกรดเวอร์ชันเก่า

• หลังจากอัปเกรดเป็น 5.5.0 แล้ว MA AppKey จะต้องถูกส่งผ่านอย่างชัดเจนโดยใช้ MTMAConfig
• ไม่จำเป็นต้องรอการเชื่อมต่อที่ยาวนานของ AppPush หรือการลงทะเบียนสำเร็จเพื่อโทรไปที่ MA start
• start(CallBack) และ start(UserIdentity, CallBack) ล้าสมัยแล้ว โปรดใช้ start(MTMAConfig, MTMAInitResultCallback) สำหรับเวอร์ชันสแตนด์อโลน
• แอปพลิเคชันที่แต่เดิมใช้ AppPush และ MA ในเวลาเดียวกันสามารถรวม AppPush ต่อไปได้ แต่จำเป็นต้องเริ่มต้นแยกกัน
• MA RID และ AppPush RID เป็นตัวระบุอุปกรณ์อิสระสองตัว โปรดรับและใช้งานผ่าน SDK ที่เกี่ยวข้องตามลำดับ อย่าใช้อันหนึ่งเป็นอันอื่น

สำหรับอินเทอร์เฟซทางธุรกิจอื่นๆ โปรดดู คู่มือ API