مشاركة فاتورة PDF من تطبيقك إلى واتساب تفشل: استخدم FileProvider
باختصار: إذا كان تطبيقك على أندرويد ينشئ فاتورة أو عرض سعر بصيغة PDF، وزر «مشاركة عبر واتساب» يجعل التطبيق يتوقف فجأة، أو يفتح واتساب ثم يقول إن الملف غير موجود، فغالباً يحاول التطبيق مشاركة الملف بمسار file://. توثيق أندرويد يشرح أن هذا الأسلوب غير مستحسن لأن التطبيق المستقبل قد لا يملك صلاحية الوصول للمسار، وأن التطبيقات التي تستهدف أندرويد 7.0 فما فوق قد تواجه الاستثناء FileUriExposedException. الطريقة الصحيحة هي FileProvider، الذي ينشئ رابط content:// للملف ويمنح التطبيق المستقبل إذناً مؤقتاً للقراءة.
الشكوى من أرض الواقع
شركة صيانة مكيفات في عمّان لديها تطبيق للفنيين. بعد كل زيارة، ينشئ الفني من التطبيق ملف PDF فيه تفاصيل العمل والقطع المستبدلة، ثم يضغط «إرسال للزبون عبر واتساب». على بعض الهواتف يتوقف التطبيق كلياً عند الضغط. على هواتف أخرى يفتح واتساب، لكن الملف لا يصل، أو تظهر رسالة أن الملف لا يمكن فتحه.
النتيجة: الفني يلتقط صورة للشاشة ويرسلها بدل الفاتورة، والشركة تبدو أقل احترافية. هذا مثال توضيحي لمشكلة شائعة في تطبيقات الخدمات الميدانية.
لماذا لا تعمل المشاركة بالمسار المباشر؟
كل تطبيق في أندرويد يعيش في مساحة خاصة به. ملف الفاتورة الذي أنشأه تطبيقك محفوظ في مجلد يخصه، وواتساب تطبيق آخر لا يستطيع الدخول إلى هذا المجلد.
عندما يرسل تطبيقك إلى واتساب مساراً مباشراً من نوع file://، فهو كمن يعطي شخصاً عنوان غرفة مغلقة دون مفتاح. توثيق FileUriExposedException يوضح ذلك: كشف مسارات file:// غير مستحسن لأن التطبيق المستقبل قد لا يملك صلاحية الوصول إلى المسار المشترك. ويضيف أن على التطبيقات استخدام روابط content:// بدلاً من ذلك، كي تستطيع المنصة منح التطبيق المستقبل إذناً مؤقتاً للوصول إلى الملف.
ويذكر التوثيق أن هذا الاستثناء يُطلق فقط للتطبيقات التي تستهدف إصدار أندرويد 7.0 أو أعلى. لهذا قد تكون المشاركة «تعمل» في نسخة قديمة من التطبيق، ثم تتعطل فجأة بعد أن يرفع المطور الإصدار المستهدف عند تحديث التطبيق.
الاستثناء ليس أداة أمان
نقطة يذكرها التوثيق تستحق الانتباه: هذا الاستثناء أداة تشخيص للمطورين، ولا يُطلق دائماً عند كشف مسار file://، لذلك لا يجب الاعتماد عليه لأغراض الأمان في أي إصدار. بمعنى آخر: إذا لم يتوقف التطبيق على هاتفك، فهذا لا يعني أن المشاركة صحيحة. قد تفشل بصمت عند زبون آخر.
الحل: FileProvider
توثيق أندرويد يصف FileProvider بأنه نوع خاص من مزودي المحتوى يسهّل مشاركة الملفات المرتبطة بالتطبيق بأمان، بإنشاء رابط content:// للملف بدلاً من رابط file:///. ويشرح أن رابط المحتوى يسمح بمنح صلاحية قراءة أو كتابة مؤقتة.
خطوات الإعداد كما يشرحها التوثيق، بلغة مبسطة لتتابعها مع المطور:
- تعريف المزود في ملف التطبيق: مع تعيين android:exported بقيمة false، لأن المزود لا يحتاج أن يكون عاماً، وتعيين android:grantUriPermissions بقيمة true للسماح بمنح وصول مؤقت للملفات. ويُفضل أن يكون اسم الصلاحية مبنياً على نطاق تملكه.
- تحديد المجلدات المسموح مشاركتها: في ملف XML داخل المشروع، مثل res/xml/file_paths.xml، تُذكر المجلدات التي يُسمح بمشاركة ملفات منها فقط، مثل مجلد الملفات الداخلي أو مجلد الذاكرة المؤقتة.
- إنشاء رابط المحتوى: عند المشاركة، يمرر التطبيق ملف الفاتورة إلى الدالة getUriForFile ليحصل على رابط content://.
- منح إذن القراءة: يضيف التطبيق إلى طلب المشاركة علامة FLAG_GRANT_READ_URI_PERMISSION. التوثيق يذكر أن هذا يمنح إذناً مؤقتاً للرابط.
- إرسال الطلب: بنوع الملف المناسب، أي PDF، فيظهر واتساب وغيره في قائمة المشاركة ويستطيع قراءة الملف.
كم يدوم إذن الوصول؟
ميزة هذا الأسلوب أن الإذن مؤقت. التوثيق يذكر أن الأذونات التي تُضاف إلى طلب المشاركة تبقى متاحة للتطبيق المستقبل طالما بقيت الشاشة المستقبلة نشطة، وأنه عند إرسالها إلى خدمة تبقى متاحة طالما الخدمة تعمل. ويذكر طريقة أخرى لمنح الإذن مباشرة لتطبيق محدد، وفي هذه الحالة يبقى الإذن سارياً إلى أن يُلغى بدالة revokeUriPermission أو يُعاد تشغيل الجهاز.
بالمقارنة، يوضح التوثيق أن التحكم في الوصول لمسار file:/// يتطلب تعديل صلاحيات نظام الملفات للملف نفسه، وهذه الصلاحيات تبقى متاحة لأي تطبيق، وهذا ما يجعل الأسلوب القديم أقل أماناً.
مشاركة أكثر من ملف
أحياناً يريد الفني إرسال الفاتورة مع صور قبل وبعد الصيانة. التوثيق يشرح أن طلب المشاركة يمكن أن يحمل أكثر من رابط محتوى عبر ClipData، ويذكر حالة الأجهزة القديمة جداً التي تحتاج إرسال رابط واحد في كل مرة. اطلب من المطور أن يجرّب مشاركة عدة ملفات معاً إذا كانت هذه حاجة فعلية لفريقك.
أين تُحفظ الفواتير قبل مشاركتها؟
اختيار المجلد مهم. التوثيق يعدد أنواع المسارات التي يمكن تعريفها، منها مجلد files الداخلي ومجلد cache الداخلي. اقتراح عملي:
- الفواتير المؤقتة التي تُنشأ للمشاركة فقط يمكن حفظها في مجلد الذاكرة المؤقتة، لأنها لا تحتاج أن تبقى على الهاتف.
- الفواتير التي يحتاجها الفني لاحقاً دون اتصال قد تُحفظ في مجلد الملفات الداخلي.
ولا تعرّف في ملف المسارات مجلداً أوسع من اللازم. إذا سمحت بمشاركة كل ملفات التطبيق، فأنت توسع ما يمكن أن يصل إلى تطبيقات أخرى دون داعٍ.
نصائح لتجربة أفضل للفني والزبون
- اسم ملف واضح: مثل «فاتورة-زيارة-1287.pdf» بدل اسم عشوائي، لأن الزبون يرى الاسم في واتساب. هذا مثال توضيحي لاسم الملف.
- حجم معقول: ملف PDF فيه صور كثيرة بدقة عالية قد يتأخر إرساله على شبكة ضعيفة. ضغط الصور داخل الفاتورة يساعد.
- رسالة مرافقة: يمكن أن يرافق المشاركة نص قصير يشرح محتوى الملف ورقم الزيارة.
- بديل عند الفشل: إذا فشلت المشاركة، اعرض خيار حفظ الملف أو إرساله بالبريد بدل أن يتوقف التطبيق.
كيف تختبر الإصلاح؟
- أنشئ فاتورة وشاركها عبر واتساب إلى رقمك. افتح الملف من المحادثة.
- شاركها عبر البريد الإلكتروني وتطبيق ملفات آخر.
- كرر على هاتف بإصدار أندرويد حديث وآخر أقدم.
- أغلق التطبيق بعد المشاركة مباشرة، وتأكد أن الملف ما زال يُفتح من واتساب.
- جرّب مشاركة فاتورتين متتاليتين للتأكد أن الثانية لا تستبدل الأولى بالخطأ.
أسئلة شائعة
ليش التطبيق بيسكّر لما أشارك الفاتورة على واتساب؟
غالباً لأنه يشارك الملف بمسار file://، وأندرويد قد يطلق استثناء FileUriExposedException للتطبيقات التي تستهدف إصدار 7.0 فما فوق.
شو هو FileProvider؟
مزود محتوى خاص ينشئ رابط content:// للملف ويسمح بمنح التطبيق المستقبل إذن قراءة مؤقتاً.
المشاركة شغالة عندي، يعني ما في مشكلة؟
ليس بالضرورة. التوثيق يقول إن الاستثناء لا يُطلق دائماً، فقد تفشل المشاركة بصمت عند غيرك.
وين الأفضل أحفظ الفواتير؟
الفواتير المؤقتة في مجلد الذاكرة المؤقتة، والتي يحتاجها الفني لاحقاً في مجلد الملفات الداخلي، مع تعريف المجلدات اللازمة فقط.
إذا كانت مشاركة الملفات من تطبيقك تتعطل أو تصل فارغة، تواصل معنا ونرتبها معك.