قوالب مصادقة الملء التلقائي بضغطة واحدة

تسمح لك قوالب مصادقة الملء التلقائي بضغطة واحدة بإرسال كلمة سر أو رمز لمرة واحدة إلى جانب زر الملء التلقائي بضغطة واحدة إلى المستخدمين. عندما يضغط مستخدم واتساب على زر الملء التلقائي، يعمل عميل واتساب على تشغيل نشاط يقوم بفتح التطبيق ويرسل له كلمة السر أو الرمز.

تتكون قوالب مصادقة زر الملء التلقائي بضغطة واحدة مما يلي:

• نص تم تعيينه مسبقًا: <VERIFICATION_CODE> هو رمز التحقق.
• إخلاء مسؤولية أمنية اختياري: لأغراض الأمان، لا تشارك هذا الرمز.
• تحذير انتهاء الصلاحية (اختياري): تنتهي صلاحية هذا الرمز في غضون <NUM_MINUTES> دقيقة.
• زر الملء التلقائي بضغطة واحدة.

التقييدات

أزرار الملء التلقائي بضغطة واحدة مدعومة فقط في نظام Android. إذا أرسلت قالب مصادقة إلى مستخدم واتساب يستخدم جهاز بنظام تشغيل بخلاف Android، فسيعرض عميل واتساب زر نسخ الرمز بدلاً من ذلك.

لا يتم دعم عناوين URL والوسائط والرموز التعبيرية.

إنشاء القالب

استخدم نقطة نهاية حساب واتساب للأعمال > قوالب الرسائل لإنشاء قوالب المصادقة.

بنية الطلب

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates

نص المنشور

{
  "name": "<TEMPLATE_NAME>",
  "language": "<TEMPLATE_LANGUAGE>",
  "category": "authentication",
  "message_send_ttl_seconds": <TIME_T0_LIVE>, // Optional
  "components": [
    {
      "type": "body",
      "add_security_recommendation": <SECURITY_RECOMMENDATION> // Optional
    },
    {
      "type": "footer",
      "code_expiration_minutes": <CODE_EXPIRATION> // Optional
    },
    {
      "type": "buttons",
      "buttons": [
        {
          "type": "otp",
          "otp_type": "one_tap",
          "text": "<COPY_CODE_BUTTON_TEXT>",  // Optional
          "autofill_text": "<AUTOFILL_BUTTON_TEXT>", // Optional
          "supported_apps": [
            { 
              "package_name": "<PACKAGE_NAME>",
              "signature_hash": "<SIGNATURE_HASH>"
            }
          ]
        }
      ]
    }
  ]
}

لاحظ أنه في طلب إنشاء القالب، يتم تحديد نوع الزر كـ otp، ولكن عند الإنشاء سيتم تعيين نوع الزر على url. يمكنك تأكيد ذلك عن طريق تنفيذ طلب GET على قالب مصادقة تم إنشاؤه مؤخرًا وتحليل المكونات.

الخصائص

مثال على الطلب

في هذا المثال يتم إنشاء قالب يسمى "authentication_code_autofill_button" ويتم تصنيفه كـ authentication مع تمكين كل سلاسل النص الاختيارية وزر الملء التلقائي بضغطة واحدة.

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_autofill_button",
  "language": "en_US",
  "category": "authentication",
  "message_send_ttl_seconds": 60,
  "components": [
    {
      "type": "body",
      "add_security_recommendation": true
    },
    {
      "type": "footer",
      "code_expiration_minutes": 10
    },
    {
      "type": "buttons",
      "buttons": [
        {
          "type": "otp",
          "otp_type": "one_tap",
          "text": "Copy Code",
          "autofill_text": "Autofill",
          "package_name": "com.example.luckyshrub",
          "signature_hash": "K8a/AINcGX7"
        }
      ]
    }
  ]
}'

مثال على الاستجابة

{
  "id": "594425479261596",
  "status": "PENDING",
  "category": "AUTHENTICATION"
}

علامة تجزئة مفتاح التوقيع في التطبيق

./sms_retriever_hash_v9.sh --package "com.example.myapplication" --keystore ~/.android/debug.keystore

التطبيقات المدعومة

"buttons": [
  {
    "type": "otp",
    ...
    "supported_apps": [
      { 
        "package_name": "<PACKAGE_NAME_1>",
        "signature_hash": "<SIGNATURE_HASH_1>"
      },
      { 
        "package_name": "<PACKAGE_NAME_2>",
        "signature_hash": "<SIGNATURE_HASH_2>"
      },
      ...
    ]
  }
]

"buttons": [
  {
    "type": "otp",
    ...
    "package_name": "<PACKAGE_NAME>",
    "signature_hash": "<SIGNATURE_HASH>"
  }
]

المصادقة

يجب أن ترسل إشارة إلى عميل واتساب لتوقع التسليم الوشيك لكلمة سر أو رمز. يمكنك إجراء ذلك عن طريق بدء "المصادقة".

تمثل عملية المصادقة كائن مراسلة في Android وفئة عامة يمكنك تنفيذها، ولكن يمكن لعميل واتساب وحده أن يبدأها.

عندما يطلب مستخدم التطبيق كلمة سر لمرة واحدة أو رمز تحقق ويختار إرساله إلى رقم واتساب، احرص أولاً على إجراء المصادقة ثم قم باستدعاء API لإرسال رسالة قالب المصادقة. عندما يتلقى عميل واتساب الرسالة، سيقوم بإجراء تحقق من الأهلية وإذا لم يتم العثور على أي أخطاء، فيمكنك بدء هدف المراسلة وعرض الرسالة على المستخدم. وأخيرًا، عندما يضغط المستخدم على زر الملء التلقائي بضغطة واحدة في الرسالة، سنعمل تلقائيًا على تحميل التطبيق وإدخال كلمة السر أو الرمز فيه.

إذا لم تقم بإجراء تأكيد الاتصال قبل إرسال الرسالة أو فشلت الرسالة في التحقق من الأهلية، فستعرض الرسالة المرسلة زر نسخ الرمز بدلاً من زر الضغطة الواحدة.

التحقق من الأهلية

يُجري عميل واتساب عمليات التحقق التالية عند تلقيه رسالة قالب المصادقة. إذا فشلت أي عملية تحقق، فسيتم استبدال زر الملء التلقائي بضغطة واحدة بزر نسخ الرمز.

• تم بدء تأكيد الاتصال منذ أقل من 10 دقائق (أو أقل من عدد الدقائق المحدد بواسطة خاصية code_expiration_minutes للقالب، إذا كانت موجودة).
• يطابق اسم الحزمة في الرسالة (المحدد في الخاصية package_name في المصفوفة components عند إنشاء القالب) اسم الحزمة الذي تم تعيينه في كائن المراسلة. يتم تحديد التطابق عبر الأسلوب getCreatorPackage الذي يتم استدعاؤه في الكائن PendingIntent المتوفر بواسطة التطبيق.
• لم يبدأ أي من التطبيقات الأخرى التي قمت بتضمينها في قائمة supported_apps للقالب عملية تأكيد الاتصال خلال آخر 10 دقائق (أو عدد الدقائق المشار إليها بواسطة خاصية code_expiration_minutes للقالب، إن وجدت).
• تطابق علامة تجزئة مفتاح التوقيع في التطبيق (المحددة في الخاصية signature_hash في مصفوفة المكونات عند إنشاء القالب) علامة تجزئة مفتاح التوقيع في التطبيق المثبت.
• تتضمن الرسالة نص زر الملء التلقائي بضغطة واحدة.
• حدد التطبيق نشاطًا لتلقي كلمة السر أو الرمز.

إشعارات Android

لن تظهر إشعارات Android التي تشير إلى استلام رسالة قالب المصادقة في واتساب إلا على جهاز Android الخاص بالمستخدم إذا:

• قام المستخدم بتسجيل الدخول إلى تطبيق واتساب أو تطبيق واتساب للأعمال برقم الهاتف (الحساب) الذي تم إرسال الرسالة له.
• قام المستخدم بتسجيل الدخول إلى التطبيق.
• إصدار نظام تشغيل Android هو KitKat (4.4، API 19) أو إصدار أحدث.
• تم تمكين عرض الإشعارات (الإعدادات > الإشعارات) في تطبيق واتساب أو تطبيق واتساب للأعمال.
• تم تمكين الإشعار على مستوى الجهاز في تطبيق واتساب أو تطبيق واتساب للأعمال.
• لم يتم كتم سلاسل الرسائل السابقة في تطبيق واتساب أو تطبيق واتساب للأعمال بين المستخدم والنشاط التجاري.

استخدام مجموعة SDK (إصدار تجريبي)

تتوفر مجموعة OTP Android SDK بالإصدار التجريبي. يمكن استخدامها لإجراء عمليات المصادقة، بالإضافة إلى وظائف أخرى في كل من قوالب مصادقة الملء التلقائي بضغطة واحدة وبدون أي ضغطات.

للوصول إلى وظائف مجموعة SDK، أضف التكوين التالي إلى ملف Gradle:

dependencies {
  …
  implementation 'com.whatsapp.otp:whatsapp-otp-android-sdk:0.1.0'
  …
}

أضف mavenCentral() إلى المستودعات:

repositories {
  …
  mavenCentral()
  …
}

النشاط

قم بالإعلان عن نشاط وفلتر هدف مراسلة الذي يمكنه تلقي كلمة سر لمرة واحدة أو الرمز. يجب أن يحتوي فلتر هدف المراسلة على اسم الإجراء com.whatsapp.otp.OTP_RETRIEVED.

<activity
   android:name=".ReceiveCodeActivity"
   android:enabled="true"
   android:exported="true"
   android:launchMode="standard">
   <intent-filter>
       <action android:name="com.whatsapp.otp.OTP_RETRIEVED" />
   </intent-filter>
</activity>

هذا هو النشاط الذي سيبدأه تطبيق واتساب أو تطبيق واتساب للأعمال بمجرد تلقي رسالة قالب المصادقة وتخطيها لكل عمليات التحقق من الأهلية.

فئة النشاط

استخدام مجموعة SDK (المفضل)

حدّد فئة النشاط العامة وأنشئ مثيلاً لكائن WhatsAppOtpIncomingIntentHandler لمعالجة الهدف والتحقق من رمز OTP ومعالجة الأخطاء.

public class ReceiveCodeActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      WhatsAppOtpIncomingIntentHandler incomingIntentHandler = new WhatsAppOtpIncomingIntentHandler();
      incomingIntentHandler.processOtpCode(
                             intent,
                             // call your function to validate
                             (code) -> validateCode(code),
                             // call your function to handle errors
                             (error, exception) -> handleError(error, exception));
}

بدون مجموعة SDK

حدّد فئة النشاط العامة التي يمكنها قبول الرمز بمجرد إرساله إلى التطبيق.

public class ReceiveCodeActivity extends AppCompatActivity {

   @Override
   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       Intent intent = getIntent();
       // retrieve PendingIntent from extras bundle
       PendingIntent pendingIntent = intent.getParcelableExtra("_ci_");
       // verify source of the pendingIntent
       String pendingIntentCreatorPackage = pendingIntent.getCreatorPackage();
       // check if creatorPackage is "com.whatsapp" -> WA consumer app Or
       // "com.whatsapp.w4b" -> WA business app
       if ("com.whatsapp".equals(creatorPackage) || "com.whatsapp.w4b".equals(creatorPackage)) {
         // use OTP code
         String otpCode = intent.getStringExtra("code");
       }
   }
}

بدء تأكيد الاتصال

استخدام مجموعة SDK (المفضل)

يمكن إجراء المصادقة عن طريق إنشاء مثيل للكائن WhatsAppOtpHandler وتمرير السياق إلى أسلوب .sendOtpIntentToWhatsApp():

WhatsAppOtpHandler whatsAppOtpHandler = new WhatsAppOtpHandler();
whatsAppOtpHandler.sendOtpIntentToWhatsApp(context);

بدون مجموعة SDK

يعرض هذا المثال طريقةً لبدء المصادقة مع عميل واتساب.

public void sendOtpIntentToWhatsApp() {
   // Send OTP_REQUESTED intent to both WA and WA Business App
   sendOtpIntentToWhatsApp("com.whatsapp");
   sendOtpIntentToWhatsApp("com.whatsapp.w4b");
}

private void sendOtpIntentToWhatsApp(String packageName) {

  /**
  * Starting with Build.VERSION_CODES.S, it will be required to explicitly
  * specify the mutability of  PendingIntents on creation with either
  * (@link #FLAG_IMMUTABLE} or FLAG_MUTABLE
  */
  int flags = Build.VERSION.SDK_INT >= Build.VERSION_CODES.S ? FLAG_IMMUTABLE : 0;
  PendingIntent pi = PendingIntent.getActivity(
      getApplicationContext(),
      0,
      new Intent(),
      flags);


  // Send OTP_REQUESTED intent to WhatsApp
  Intent intentToWhatsApp = new Intent();
  intentToWhatsApp.setPackage(packageName);
  intentToWhatsApp.setAction("com.whatsapp.otp.OTP_REQUESTED");
  // WA will use this to verify the identity of the caller app.
  Bundle extras = intentToWhatsApp.getExtras();
  if (extras == null) {
     extras = new Bundle();
  }
  extras.putParcelable("_ci_", pi);
  intentToWhatsApp.putExtras(extras);
  getApplicationContext().sendBroadcast(intentToWhatsApp);
}

التحقق من تثبيت واتساب

يمكنك التحقق من تثبيت واتساب قبل تقديم واتساب كخيار إذا كنت تتوقع وجود كل من واتساب وتطبيقك على الجهاز ذاته.

أولاً، يجب إضافة ما يلي إلى ملف AndroidManifest.xml:

<queries>
    <package android:name="com.whatsapp"/>
    <package android:name="com.whatsapp.w4b"/>
</queries>

استخدام مجموعة SDK (المفضل)

أنشئ مثيلاً للكائن WhatsAppOtpHandler:

WhatsAppOtpHandler whatsAppOtpHandler = new WhatsAppOtpHandler();

تحقق مما إذا تم تثبيت عميل واتساب عن طريق تمرير الأسلوب isWhatsAppInstalled كفقرة في بيان If:

If (whatsAppOtpHandler.isWhatsAppInstalled(context)) {
    // ... do something
}

بدون مجموعة SDK

if (this.isWhatsAppInstalled(context)) {
    // ... do something
} 

public boolean isWhatsAppInstalled(final @NonNull Context context){
    return isWhatsAppInstalled(context, "com.whatsapp") || 
           isWhatsAppInstalled(context, "com.whatsapp.w4b");
  }

  public boolean isWhatsAppInstalled(final @NonNull Context context,
      final @NonNull String type){
    final Intent intent = new Intent();
    intent.setPackage(type);
    intent.setAction("com.whatsapp.otp.OTP_REQUESTED");
    PackageManager packageManager = context.getPackageManager();
    List<ResolveInfo> receivers = packageManager.queryBroadcastReceivers(intent, 0);
    return !receivers.isEmpty();
  }
}

إرسال رسائل قوالب المصادقة

استخدم API السحابة أو API داخل المواقع لإرسال رسائل قالب المصادقة.

• إرسال رسائل قوالب المصادقة باستخدام API السحابة
• إرسال رسائل قوالب المصادقة باستخدام API داخل المواقع

لاحظ أنه يجب أولاً بدء المصادقة بين التطبيق وعميل واتساب. راجع المصادقة أعلاه.

إشارات الأخطاء

راجع إشارات الأخطاء التي قد تساعدك في تصحيح الأخطاء.

عينة التطبيق

راجع عينة تطبيق يحتوي على كلمة سر لمرة واحدة (OTP) في واتساب لنظام Android على Github. تعرض عينة التطبيق كيفية إرسال كلمات سر OTP والرموز وتلقيها عبر API وكيفية دمج أزرار الملء التلقائي بضغطة واحدة وأزرار نسخ الرمز وكيفية إنشاء قالب وكيفية تشغيل عينة من الخادم.