استخدام حِزم تطوير البرامج (SDK) لنظام التشغيل Android التي تم إنشاؤها

تتيح لك حِزم تطوير البرامج (SDK) من جهة العميل Firebase Data Connect إرسال طلبات البحث والتعديلات من جهة الخادم مباشرةً من تطبيق Firebase. ويمكنك إنشاء حزمة تطوير برامج (SDK) مخصّصة من جهة العميل بالتزامن مع تصميم المخططات وطلبات البحث والتعديلات التي تنشرها في خدمة Data Connect. بعد ذلك، يمكنك دمج طرق من حزمة تطوير البرامج هذه في منطق برنامجك.

كما ذكرنا في موضع آخر، من المهم الإشارة إلى أنّ Data Connect طلبات البحث وعمليات التعديل لا يتم إرسالها من خلال رمز العميل وتنفيذها على الخادم. في المقابل، عند نشر عمليات Data Connect، يتم تخزينها على الخادم مثل "وظائف السحابة الإلكترونية". وهذا يعني أنّه عليك نشر تغييرات مقابلة من جهة العميل لتجنُّب تعطيل التطبيق للمستخدمين الحاليين (على سبيل المثال، في إصدارات التطبيق القديمة).

لهذا السبب، يوفّر لك Data Connect بيئة تطوير وأدوات تتيح لك إنشاء نماذج أولية للمخططات والطلبات وعمليات التعديل التي يتم نشرها على الخادم. تنشئ أيضًا حِزم SDK من جهة العميل تلقائيًا أثناء إنشاء النماذج الأولية.

بعد تكرار التحديثات على خدمتك وتطبيقات العميل، يصبح كلا التحديثَين على جهة الخادم ومن جهة العميل جاهزًا للنشر.

ما هي خطوات سير عمل تطوير العملاء؟

إذا اتّبعت الخطوات الواردة في البدء، تكون قد تعرّفت على سير عملية التطوير بشكل عام في Data Connect. في هذا الدليل، ستجد معلومات أكثر تفصيلاً حول إنشاء حِزم تطوير البرامج (SDK) لنظام Android من المخطط الخاص بك والتعامل مع طلبات البحث وعمليات التعديل من جهة العميل.

باختصار، لاستخدام حِزم تطوير البرامج (SDK) التي تم إنشاؤها لنظام التشغيل Android في تطبيقات العميل، عليك اتّباع خطوات المتطلبات الأساسية التالية:

  1. أضِف Firebase إلى تطبيق Android.
  2. اضبط Data Connect كعنصر تابع في Gradle.
  3. أضِف المكوّن الإضافي لنظام Gradle المتوافق مع Kotlin Serialization واعتمادية Gradle.

بعد ذلك:

  1. طوِّر مخطّط تطبيقك.

  2. إعداد إنشاء حزمة تطوير البرامج (SDK):

    • باستخدام الزر إضافة حزمة تطوير البرامج (SDK) إلى التطبيق في إضافة Data Connect VS Code
    • من خلال تعديل connector.yaml

  3. تهيئة رمز العميل واستيراد المكتبات

  4. تنفيذ طلبات البحث وعمليات التعديل

  5. إعداد Data Connect المحاكي واستخدامه والتكرار

إنشاء حزمة تطوير البرامج (SDK) بلغة Kotlin

استخدِم واجهة سطر الأوامر Firebase لإعداد حِزم تطوير البرامج (SDK) التي تم إنشاؤها باستخدام Data Connect في تطبيقاتك. يجب أن يرصد الأمر init جميع التطبيقات في المجلد الحالي وأن يثبّت حِزم SDK التي تم إنشاؤها تلقائيًا.

firebase init dataconnect:sdk

تحديث حِزم SDK أثناء إنشاء النماذج الأولية

إذا كانت إضافة Data Connect VS Code مثبَّتة، ستحرص دائمًا على أن تكون حِزم SDK التي تم إنشاؤها حديثة.

إذا كنت لا تستخدم إضافة Data Connect في VS Code، يمكنك استخدام Firebase CLI لإبقاء حِزم SDK التي تم إنشاؤها محدّثة.

firebase dataconnect:sdk:generate --watch

إنشاء حِزم SDK في مسارات الإنشاء

يمكنك استخدام Firebase CLI لإنشاء حِزم تطوير البرامج (SDK) الخاصة بـ Data Connect في عمليات إنشاء CI/CD.

firebase dataconnect:sdk:generate

إعداد رمز العميل

تضمين Data Connect في رمز العميل

لإعداد رمز العميل لاستخدام Data Connect وحزمة تطوير البرامج (SDK) التي تم إنشاؤها، اتّبِع أولاً تعليمات الإعداد العادية في Firebase.

بعد ذلك، أضِف ما يلي إلى القسم plugins في app/build.gradle.kts:

// The Firebase team tests with version 1.8.22; however, other 1.8 versions,
// and all newer versions are expected work too.
kotlin("plugin.serialization") version "1.8.22" // MUST match the version of the Kotlin compiler

بعد ذلك، أضِف ما يلي إلى القسم dependencies في app/build.gradle.kts:

implementation(platform("com.google.firebase:firebase-bom:34.12.0"))
implementation("com.google.firebase:firebase-dataconnect")
implementation("com.google.firebase:firebase-auth") // Optional
implementation("com.google.firebase:firebase-appcheck") // Optional
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3") // Newer versions should work too
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1") // Newer versions should work too

إعداد Data Connect Android SDK

ابدأ مثيل Data Connect باستخدام المعلومات التي استخدمتها لإعداد Data Connect (تتوفّر جميعها في علامة التبويب Data Connect في وحدة تحكّم Firebase).

عنصر ConnectorConfig

يتطلّب حزمة تطوير البرامج (SDK) كائن إعدادات موصّل.

يتم إنشاء هذا العنصر تلقائيًا من serviceId وlocation في dataconnect.yaml، ومن connectorId في connector.yaml.

الحصول على مثيل موصّل

بعد إعداد عنصر الإعداد، احصل على مثيل Data Connect لأداة الربط. سيتم إنشاء رمز الموصل بواسطة محاكي Data Connect. إذا كان اسم الموصّل هو movies وكانت حزمة Kotlin هي com.myapplication، كما هو موضّح في connector.yaml، يمكنك استرداد عنصر الموصّل من خلال طلب:

val connector = com.myapplication.MoviesConnector.instance

استخدام طلبات البحث وعمليات التعديل من حزمة تطوير البرامج (SDK) لنظام التشغيل Android

باستخدام عنصر الموصل، يمكنك تنفيذ طلبات البحث وعمليات التعديل كما هو محدّد في رمز مصدر GraphQL. لنفترض أنّ الموصل يتضمّن العمليات المحدّدة التالية:

mutation createMovie($title: String!, $releaseYear: Int!, $genre: String!, $rating: Int!) {
  movie_insert(data: {
    title: $title
    releaseYear: $releaseYear
    genre: $genre
    rating: $rating
  })
}

query getMovieByKey($key: Movie_Key!) {
  movie(key: $key) { id title }
}

query listMoviesByGenre($genre: String!) {
  movies(where: {genre: {eq: $genre}}) {
    id
    title
  }
}

يمكنك بعد ذلك إنشاء فيلم واسترداده على النحو التالي:

val connector = MoviesConnector.instance

val addMovieResult1 = connector.createMovie.execute(
  title = "Empire Strikes Back",
  releaseYear = 1980,
  genre = "Sci-Fi",
  rating = 5
)

val movie1 = connector.getMovieByKey.execute(addMovieResult1.data.key)

println("Empire Strikes Back: ${movie1.data.movie}")

يمكنك أيضًا استرداد أفلام متعددة:

val connector = MoviesConnector.instance

val addMovieResult2 = connector.createMovie.execute(
  title="Attack of the Clones",
  releaseYear = 2002,
  genre = "Sci-Fi",
  rating = 5
)

val listMoviesResult = connector.listMoviesByGenre.execute(genre = "Sci-Fi")

println(listMoviesResult.data.movies)

يمكنك أيضًا جمع Flow التي لن تعرض نتيجة إلا عند استرجاع نتيجة طلب بحث جديدة باستخدام طلب إلى طريقة execute() الخاصة بطلب البحث.

val connector = MoviesConnector.instance

connector.listMoviesByGenre.flow(genre = "Sci-Fi").collect { data ->
  println(data.movies)
}

connector.createMovie.execute(
  title="A New Hope",
  releaseYear = 1977,
  genre = "Sci-Fi",
  rating = 5
)

connector.listMoviesByGenre.execute(genre = "Sci-Fi") // will cause the Flow to get notified

التعامل مع التغييرات في حقول التعداد

يمكن أن يحتوي مخطط التطبيق على تعدادات، ويمكن الوصول إليها من خلال طلبات بحث GraphQL.

عندما يتغيّر تصميم التطبيق، يمكنك إضافة قيم جديدة متوافقة مع التعداد. على سبيل المثال، لنفترض أنّك قرّرت في وقت لاحق من مراحل نشاط تطبيقك إضافة القيمة FULLSCREEN إلى تعداد AspectRatio.

في سير عمل Data Connect، يمكنك استخدام أدوات التطوير المحلية لتعديل الاستعلامات وحِزم SDK.

ومع ذلك، قبل طرح إصدار محدَّث من برامجك، قد تتعطّل البرامج القديمة التي تم نشرها.

مثال على عملية تنفيذ مرنة

تفرض حزمة تطوير البرامج (SDK) التي تم إنشاؤها التعامل مع القيم غير المعروفة، لأنّ رمز العميل يجب أن يزيل التفاف العنصر EnumValue، الذي يكون إما EnumValue.Known للقيم المعروفة في التعداد أو EnumValue.Unknown للقيم غير المعروفة.

val result = connector.listMoviesByAspectRatio.execute(AspectRatio.WIDESCREEN)
val encounteredAspectRatios = mutableSetOf<String>()

result.data.movies
  .mapNotNull { it.otherAspectRatios }
  .forEach { otherAspectRatios ->
    otherAspectRatios
      .filterNot { it.value == AspectRatio.WIDESCREEN }
      .forEach {
        when (it) {
          is EnumValue.Known -> encounteredAspectRatios.add(it.value.name)
          is EnumValue.Unknown ->
            encounteredAspectRatios.add("[unknown ratio: ${it.stringValue}]")
        }
      }
  }

println(
  "Widescreen movies also include additional aspect ratios: " +
    encounteredAspectRatios.sorted().joinToString()
)

تفعيل التخزين المؤقت من جهة العميل

يتضمّن Data Connect ميزة اختيارية للتخزين المؤقت من جهة العميل، ويمكنك تفعيلها من خلال تعديل ملف connector.yaml. عند تفعيل هذه الميزة، ستخزّن حِزم تطوير البرامج (SDK) للعميل التي تم إنشاؤها ردود الطلبات مؤقتًا على الجهاز، ما قد يقلّل عدد طلبات قاعدة البيانات التي يرسلها تطبيقك ويتيح تشغيل الأجزاء التي تعتمد على قاعدة البيانات في تطبيقك عند انقطاع الاتصال بالشبكة.

لتفعيل التخزين المؤقت من جهة العميل، أضِف إعدادات التخزين المؤقت من جهة العميل إلى إعدادات الموصل:

generate:
  kotlinSdk:
    outputDir: "../android"
    package: "com.google.firebase.dataconnect.generated"
    clientCache:
      maxAge: 5s
      storage: persistent

يتضمّن هذا الإعداد مَعلمتَين، وكلاهما اختياري:

  • ‫maxAge: الحد الأقصى لعمر الرد المخزّن مؤقتًا قبل أن تجلب حزمة SDK للعميل قيمًا جديدة. أمثلة: "0" أو "30 ثانية" أو "ساعة و30 دقيقة".

    القيمة التلقائية لـ maxAge هي 0، ما يعني أنّه يتم تخزين الردود مؤقتًا، ولكن ستجلب حزمة تطوير البرامج (SDK) للعميل دائمًا قيمًا جديدة. لن يتم استخدام القيم المخزّنة مؤقتًا إلا عندما يتم ضبط CACHE_ONLY على execute().

  • ‫storage: يمكن ضبط حزمة SDK الخاصة بالعميل لتخزين الردود مؤقتًا إما في مساحة التخزين persistent أو في memory. ستبقى النتائج المخزّنة مؤقتًا في مساحة تخزين persistent متاحة عند إعادة تشغيل التطبيق. في حِزم تطوير البرامج (SDK) لنظام التشغيل Android، تكون القيمة التلقائية هي persistent.

بعد تعديل إعدادات التخزين المؤقت للموصل، أعِد إنشاء حِزم تطوير البرامج (SDK) الخاصة بالعميل وأعِد إنشاء تطبيقك. بعد الانتهاء من ذلك، ستخزّن execute() الردود مؤقتًا وستستخدم القيم المخزّنة مؤقتًا وفقًا للسياسة التي أعددتها. يحدث ذلك تلقائيًا بشكل عام، بدون أي خطوات إضافية من جانبك، ولكن يُرجى ملاحظة ما يلي:

  • يكون السلوك التلقائي لـ execute() كما هو موضّح أعلاه: إذا تم تخزين نتيجة طلب البحث مؤقتًا وكانت القيمة المخزَّنة مؤقتًا ليست أقدم من maxAge، يتم استخدام القيمة المخزَّنة مؤقتًا. يُطلق على هذا السلوك التلقائي اسم سياسة PREFER_CACHE.

    يمكنك أيضًا تحديد ما إذا كان سيتم عرض القيم المخزّنة مؤقتًا فقط (CACHE_ONLY) أو جلب قيم جديدة من الخادم بدون شروط (SERVER_ONLY) عند استدعاء execute() بشكل فردي.

    val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)

    val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)

    إنشاء نموذج أولي لتطبيق Android واختباره

    تجهيز العملاء لاستخدام محاكي محلي

    يمكنك استخدام محاكي Data Connect، سواء من إضافة Data Connect VS Code أو من واجهة سطر الأوامر.

    تكون عملية إعداد التطبيق للاتصال بالمحاكي هي نفسها في كلتا الحالتين.

    val connector = MoviesConnector.instance

// Connect to the emulator on "10.0.2.2:9399"
connector.dataConnect.useEmulator()

// (alternatively) if you're running your emulator on non-default port:
connector.dataConnect.useEmulator(port = 9999)

// Make calls from your app

    للتبديل إلى موارد الإنتاج، علِّق على الأسطر الخاصة بالاتصال بالمحاكي.

    أنواع البيانات في حِزم تطوير البرامج (SDK) التي تحمل الرقم Data Connect

    يمثّل خادم Data Connect أنواع بيانات GraphQL الشائعة والمخصّصة. يتم تمثيل هذه القيم في حزمة SDK على النحو التالي.

    Data Connect النوع Kotlin
    سلسلة سلسلة
    Int Int (عدد صحيح 32 بت)
    عائم Double (قيمة عددية عائمة 64 بت)
    قيمة منطقية قيمة منطقية
    معرِّف فريد عالمي (UUID) java.util.UUID
    التاريخ com.google.firebase.dataconnect.LocalDate (كانت java.util.Date حتى الإصدار 16.0.0-beta03)
    الطابع الزمني com.google.firebase.Timestamp
    Int64 طويلة
    أي com.google.firebase.dataconnect.AnyValue