# استخدام وحدة تحديد الموقع في Pushwoosh في تطبيقات Android

<Aside type="caution">
يرجى العلم أن الرسائل المستندة إلى الموقع الجغرافي غير متاحة لأجهزة HMS (خدمات هواوي للجوال) لأنها مبنية على خدمات تحديد المواقع من Google.
</Aside>

هناك فئتان للوصول إلى الموقع في Android:

*   الوصول إلى الموقع في **المقدمة (Foreground)**
*   الوصول إلى الموقع في **الخلفية (Background)**

لتحديث موقع المستخدم في **المقدمة (foreground)**، يجب استيفاء أحد الشروط التالية:

*   أحد أنشطة التطبيق نشط
*   تم تشغيل خدمة المقدمة (Foreground service) من نوع `foregroundServiceType = “location”` للتطبيق

يسمح الوصول في **الخلفية (Background)** للتطبيق بالحصول على الموقع الجغرافي للمستخدم بينما يكون التطبيق غير نشط، ولم يتم تشغيل أي خدمات مقدمة (foreground services) من نوع "location" لهذا التطبيق.

## الوصول إلى الموقع في المقدمة (Foreground)

إذا كنت ستستخدم وحدة تحديد المواقع من Pushwoosh لتحديث موقع المستخدم فقط عندما يكون تطبيقك نشطًا، فأضف وحدة `pushwoosh-location` إلى ملف **app/build.gradle** الخاص بك:

```java title="build.gradle"
implementation 'com.pushwoosh:pushwoosh-location:6.+'
```

<Aside>
احصل على أحدث إصدار للوحدة من مستودع Pushwoosh على Github: [https://github.com/Pushwoosh/pushwoosh-android-sdk/releases](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases)
</Aside>

لتشغيل الوحدة، استخدم طريقة `startLocationTracking`:

<Tabs>
<TabItem label="Java">
```java
PushwooshLocation.startLocationTracking();
```
</TabItem>

<TabItem label="Kotlin">
```kotlin
PushwooshLocation.startLocationTracking()
```
</TabItem>
</Tabs>

<Aside type="note">
ستطلب وحدة `pushwoosh-location` جميع الأذونات الضرورية من المستخدم (ACCESS\_COARSE\_LOCATION, ACCESS\_FINE\_LOCATION).
</Aside>

## استخدام ForegroundService لإجراء طلبات الموقع عندما يكون تطبيقك في الخلفية

<Aside type="caution" title="متوقف دعمه">

بسبب تحديثات Android 12، لا يمكن لـ ForegroundService أن يعمل بشكل صحيح، لذا فقد تم إيقاف دعمه وسيتم إزالته من Pushwoosh SDK لاحقًا.

فيما يلي بعض الحلول البديلة لتتبع موقع المستخدمين في الخلفية:

1.  استخدم `targetSdkVersion 30` بدلاً من `31`. يرجى الأخذ في الاعتبار أن الميزات الموجودة في Android 12 لن تكون متاحة في هذه الحالة.
2.  اطلب من المستخدمين تعطيل تحسين البطارية لتطبيقك للسماح لـ ForegroundService بالبدء في الخلفية.
</Aside>

لتشغيل **ForegroundService** عند استدعاء طريقة `startLocationTracking`، والتي تسمح بالحصول على الموقع الجغرافي للمستخدم عندما يكون تطبيقك في الخلفية، اتبع الخطوات الموضحة في [الفقرة السابقة](#foreground-location-access)، ثم أضف البيانات الوصفية التالية إلى ملف **AndroidManifest.xml** الخاص بك:

```txt
...
<application>
....
    <meta-data
        android:name="com.pushwoosh.start_foreground_service"
        android:value="true" />
...
</application>
...
```

عند تشغيل **ForegroundService**، يتم إنشاء إشعار. يمكنك تخصيص الإشعار عن طريق تحديد البيانات الوصفية الإضافية في ملف **AndroidManifest.xml** الخاص بمشروعك:

```txt
...
<application>
....
    <meta-data
        android:name="com.pushwoosh.foreground_service_notification_text"
        android:value="My notification text" />
    <meta-data
        android:name="com.pushwoosh.foreground_service_notification_channel_name"
        android:value="My notification channel name" />
...
</application>
...
```

## الوصول إلى الموقع في الخلفية (Background)

لتحديث الموقع الجغرافي في الخلفية دون تشغيل ForegroundService، ستحتاج إلى ما يلي:

*   الحصول على موافقة Google Play لوصول تطبيقك إلى الموقع في الخلفية (راجع [https://support.google.com/googleplay/android-developer/answer/9799150?hl=en](https://support.google.com/googleplay/android-developer/answer/9799150?hl=en) للحصول على التفاصيل)
*   أضف الإذن إلى ملف AndroidManifest.xml الخاص بك:

```txt
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
```

*   اطلب إذن المستخدم لتحديث الموقع في الخلفية بعد الحصول على إذن الموقع في المقدمة (ابحث عن الإرشادات في وثائق مطوري Android: [https://developer.android.com/training/location/permissions#background-dialog-target-android-11](https://developer.android.com/training/location/permissions#background-dialog-target-android-11))

في الإصدار 6.3.2 من وحدة `pushwoosh-location`، قمنا بتضمين طريقة إضافية تفتح شاشة إعدادات إذن الموقع إذا تم استيفاء الشروط التالية:

*   يوجد إذن الموقع في المقدمة ممنوح للتطبيق؛
*   يوجد إذن المستخدم `ACCESS_BACKGROUND_LOCATION` في ملف AndroidManifest.xml الخاص بالتطبيق.

<Aside type="caution">
يرجى التأكد من شرح الأسباب والأغراض التي يحتاجها تطبيقك للوصول إلى موقع المستخدمين في الخلفية بوضوح. راجع [أدلة مطوري Android](https://developer.android.com/training/location/permissions#background-dialog-target-android-11) للحصول على التفاصيل.
</Aside>

استدعِ الطريقة على النحو التالي:

<Tabs>
<TabItem label="Java">
```java
PushwooshLocation.requestBackgroundLocationPermission();
```
</TabItem>

<TabItem label="Kotlin">
```
PushwooshLocation.requestBackgroundLocationPermission()
```
</TabItem>
</Tabs>

## أنواع أذونات Android 12+

[بدءًا من Android 12](https://developer.android.com/about/versions/12/approximate-location)، عند طلب إذن الوصول إلى الموقع في المقدمة، يمكن للمستخدم اختيار عدد مرات ودقة حصول التطبيق على موقع المستخدم.

هناك نوعان من تلك الأذونات:

1.  الموقع التقريبي (Approximate location)، وهو يعادل ACCESS\_COARSE\_LOCATION
2.  الموقع الدقيق (Precise location)، وهو يعادل ACCESS\_FINE\_LOCATION و ACCESS\_COARSE\_LOCATION

<Aside type="caution">
يرجى الأخذ في الاعتبار أن طلبات الموقع من التطبيقات التي تحتوي على Manifest.permission.ACCESS\_COARSE\_LOCATION وليس Manifest.permission.ACCESS\_FINE\_LOCATION سيتم تقييدها تلقائيًا إلى فاصل زمني أبطأ، وسيتم إخفاء كائن الموقع لإظهار مستوى تقريبي فقط من الدقة. راجع [https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest](https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest) للحصول على التفاصيل.
</Aside>

<Aside type="note">
ضع في اعتبارك أن مستوى الدقة يعتمد على الإذن الذي تطلبه:

*   ACCESS\_COARSE\_LOCATION – يوفر تقديرًا لموقع الجهاز، بدقة تصل إلى حوالي 1 ميل (1.6 كم).
*   ACCESS\_FINE\_LOCATION – يوفر تقديرًا لموقع الجهاز بأقصى دقة ممكنة، عادةً في حدود 160 قدمًا (50 مترًا) وأحيانًا بدقة تصل إلى 10 أقدام (بضعة أمتار) أو أفضل.

المصدر: [https://developer.android.com/training/location/permissions](https://developer.android.com/training/location/permissions)
</Aside>

## شاركنا ملاحظاتك

تساعدنا ملاحظاتك في إنشاء تجربة أفضل، لذا نود أن نسمع منك إذا واجهت أي مشاكل أثناء عملية دمج SDK. إذا واجهت أي صعوبات، فلا تتردد في مشاركة أفكارك معنا [عبر هذا النموذج](https://docs.google.com/forms/d/e/1FAIpQLSd\_0b8jwn-V\_JmoPLIxIFYbHACCQhrzidOZV3ELywoQPXRSxw/viewform).