قياس الحملات

يقدّم هذا المستند نظرة عامة حول كيفية قياس الحملات ومصادر الزيارات باستخدام الإصدار 4 من حزمة تطوير البرامج (SDK) من "إحصاءات Google" لنظام التشغيل Android.

نظرة عامة

يسمح قياس الحملات في "إحصاءات Google" بإسناد الحملات ومصادر الزيارات إلى نشاط المستخدم داخل تطبيقك. تتوفّر هذه الخيارات لتحديد مصدر الزيارات ومصادر الزيارات في الإصدار 4 من حزمة تطوير البرامج (SDK) من "إحصاءات Google" لنظام التشغيل Android:

تحديد مصدر حملات Google Play - يمكنك الاطّلاع على الحملات والمواقع الإلكترونية والتطبيقات الأخرى التي تحيل المستخدمين إلى "متجر Google Play" لتنزيل تطبيقك.
تحديد مصدر الزيارات والحملة العامة - يمكنك الاطّلاع على الحملات أو المُحيلين الذين يطلقون تطبيقك بعد تثبيته.

ستوضّح الأقسام التالية وقت تنفيذ كل نوع من أنواع قياس الحملات في تطبيقك وكيفية تنفيذه.

تحديد مصدر حملات Google Play

يتيح لك قياس حملات Google Play معرفة الحملات ومصادر الزيارات التي ترسل المستخدمين لتنزيل تطبيقك من "متجر Google Play". ننصح جميع المطوّرين بتنفيذ ميزة "قياس أداء الحملات" على "متجر Google Play".

تنفيذ إحالة حملات Google Play

يوفّر "متجر Google Play" Install Referrer API ليتمكّن المطوّرون من استرداد محتوى الإحالة من Google Play بأمان. تعرض واجهة برمجة التطبيقات هذه قيمة المَعلمة المُحيلة المُستخدَمة للوصول إلى صفحة تطبيقك على "متجر Google Play"، في حال توفُّرها.

لإحالة تنزيل تطبيق إلى حملة، يجب إضافة مَعلمة مُحيلة إلى أيّ روابط تشير إلى "متجر Google Play"، وإضافة واجهة برمجة التطبيقات Install Referrer API من Play إلى تطبيقك لتلقّي وضبط معلومات الحملة المضمّنة في الغرض على أداة تتبُّع "إحصاءات Google".

‫1. أزِل مستلِم "إحصاءات Google" من ملف AndroidManifest.xml.

إذا كان مستلِم أداة "إدارة العلامات من Google" قد نفّذه أيضًا، أزِله من ملف البيان أيضًا.

‫2. أضِف دالة تابعة إلى مكتبة واجهة برمجة التطبيقات Install Referrer API.

لإضافة التبعية، عليك تضمين ما يلي في build.gradle:

dependencies {
    ...
    implementation 'com.android.installreferrer:installreferrer:1.1'
}

‫3. عليك استدعاء واجهة برمجة التطبيقات Install Referrer API في نشاط تشغيل تطبيقك.

استخدِم واجهة برمجة التطبيقات Install Referrer API لاسترداد عنوان URL المُحيل لحزمة التطبيق المثبَّتة، ثم مرِّر قيمة عنوان URL إلى مستلِم في "إحصاءات Google" أو أداة "إدارة العلامات من Google". اتّبِع عملية تنفيذ مشابهة للرمز التالي لاستخدام واجهة برمجة التطبيقات Install Referrer API في نشاط إطلاق تطبيقك.

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

ملاحظة: هناك طريقتان خاصتان يمكنك الاختيار من بينهما. استخدِم trackInstallReferrer إذا كنت تستخدم "إحصاءات Google" فقط. استخدِم trackInstallReferrerforGTM إذا كنت تستخدم أيضًا الإصدار 4 من "إدارة العلامات من Google".

package com.example.myapplication;

import static com.android.installreferrer.api.InstallReferrerClient.InstallReferrerResponse;

import androidx.appcompat.app.AppCompatActivity;
import android.content.Intent;
import android.net.Uri;
import android.os.Bundle;
import android.os.Handler;
import android.os.RemoteException;

import com.android.installreferrer.api.InstallReferrerClient;
import com.android.installreferrer.api.InstallReferrerStateListener;
import com.android.installreferrer.api.ReferrerDetails;
import com.google.android.gms.analytics.CampaignTrackingReceiver;
import com.google.tagmanager.InstallReferrerReceiver;

import java.util.concurrent.Executor;
import java.util.concurrent.Executors;

public class MainActivity extends AppCompatActivity {

    private final Executor backgroundExecutor = Executors.newSingleThreadExecutor();

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        checkInstallReferrer();
    }

    // TODO: Change this to use whatever preferences are appropriate. The install referrer should
    // only be sent to the receiver once.
    private final String prefKey = "checkedInstallReferrer";

    void checkInstallReferrer() {
        if (getPreferences(MODE_PRIVATE).getBoolean(prefKey, false)) {
            return;
        }

        InstallReferrerClient referrerClient = InstallReferrerClient.newBuilder(this).build();
        backgroundExecutor.execute(() -> getInstallReferrerFromClient(referrerClient));
    }

    void getInstallReferrerFromClient(InstallReferrerClient referrerClient) {

        referrerClient.startConnection(new InstallReferrerStateListener() {
            @Override
            public void onInstallReferrerSetupFinished(int responseCode) {
                switch (responseCode) {
                    case InstallReferrerResponse.OK:
                        ReferrerDetails response = null;
                        try {
                            response = referrerClient.getInstallReferrer();
                        } catch (RemoteException e) {
                            e.printStackTrace();
                            return;
                        }
                        final String referrerUrl = response.getInstallReferrer();


                        // TODO: If you're using GTM, call trackInstallReferrerforGTM instead.
                        trackInstallReferrer(referrerUrl);


                        // Only check this once.
                        getPreferences(MODE_PRIVATE).edit().putBoolean(prefKey, true).commit();

                        // End the connection
                        referrerClient.endConnection();

                        break;
                    case InstallReferrerResponse.FEATURE_NOT_SUPPORTED:
                        // API not available on the current Play Store app.
                        break;
                    case InstallReferrerResponse.SERVICE_UNAVAILABLE:
                        // Connection couldn't be established.
                        break;
                }
            }

            @Override
            public void onInstallReferrerServiceDisconnected() {

            }
        });
    }

    // Tracker for Classic GA (call this if you are using Classic GA only)
    private void trackInstallReferrer(final String referrerUrl) {
        new Handler(getMainLooper()).post(new Runnable() {
            @Override
            public void run() {
                CampaignTrackingReceiver receiver = new CampaignTrackingReceiver();
                Intent intent = new Intent("com.android.vending.INSTALL_REFERRER");
                intent.putExtra("referrer", referrerUrl);
                receiver.onReceive(getApplicationContext(), intent);
            }
        });
    }

    // Tracker for GTM + Classic GA (call this if you are using GTM + Classic GA only)
    private void trackInstallReferrerforGTM(final String referrerUrl) {
        new Handler(getMainLooper()).post(new Runnable() {
            @Override
            public void run() {
                InstallReferrerReceiver receiver = new InstallReferrerReceiver();
                Intent intent = new Intent("com.android.vending.INSTALL_REFERRER");
                intent.putExtra("referrer", referrerUrl);
                receiver.onReceive(getApplicationContext(), intent);
            }
        });
    }

}

‫4. إضافة مَعلمات الحملات في "إحصاءات Google" إلى عناوين URL على Google Play

بعد ذلك، أضِف مَعلمة referrer إلى أيّ عناوين URL سيتمّ ربطها مباشرةً بـ "متجر Google Play" واضبط قيمة هذه المَعلمة على سلسلة من مَعلمات حملة "إحصاءات Google" التي تصف المصدر، كما في هذا المثال:

https://play.google.com/store/apps/details?id=com.example.application
&referrer=utm_source%3Dgoogle
%26utm_medium%3Dcpc
%26utm_term%3Drunning%252Bshoes
%26utm_content%3Dlogolink
%26utm_campaign%3Dspring_sale

لمعرفة كيفية إنشاء سلاسل مَعلمات الحملات، استخدِم أداة إنشاء عناوين URL على Google Play أو راجِع القسم المرجعي مَعلمات الحملات.

تحديد مصدر الزيارات والحملة العامة

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

// Get tracker.
Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);

// Set screen name.
t.setScreenName(screenName);

// In this example, campaign information is set using
// a url string with Google Analytics campaign parameters.
// Note: This is for illustrative purposes. In most cases campaign
//       information would come from an incoming Intent.
String campaignData = "http://examplepetstore.com/index.html?" +
    "utm_source=email&utm_medium=email_marketing&utm_campaign=summer" +
    "&utm_content=email_variation_1";

// Campaign data sent with this hit.
t.send(new HitBuilders.ScreenViewBuilder()
    .setCampaignParamsFromUrl(campaignData)
    .build()
);

راجِع الإعداد المتقدّم للحصول على تفاصيل عن طريقة getTracker.

مَعلمات الحملة

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

يحتوي الجدول أدناه على معلمات الحملات المتوفرة التي يمكن استخدامها في Google Play أو القياس العام للحملات:

المَعلمة	الوصف	أمثلة
`utm_source`	مصدر الحملة: يُستخدم لتحديد محرك بحث أو نشرة إخبارية أو مصدر آخر	`utm_source=google`
`utm_medium`	وسيط الحملة؛ يُستخدم لتحديد وسيط مثل البريد الإلكتروني أو تكلفة النقرة (CPC)	`utm_medium=cpc`
`utm_term`	عبارة الحملة؛ تُستخدم مع نتائج البحث المدفوعة لتوفير الكلمات الرئيسية للإعلانات	`utm_term=running+shoes`
`utm_content`	محتوى الحملة؛ يُستخدم لاختبار A/B والإعلانات التي تستهدف المحتوى للتمييز بين الإعلانات أو الروابط التي تشير إلى عنوان URL نفسه.	`utm_content=logolink` `utm_content=textlink`
`utm_campaign`	اسم الحملة الذي يُستخدم لتحليل الكلمات الرئيسية لتحديد ترويج منتج معيّن أو حملة استراتيجية معيّنة	`utm_campaign=spring_sale`
`gclid`	معلَمة وضع العلامات التلقائي في "إعلانات Google"، تُستخدم لقياس الإعلانات. يتم إنشاء هذه القيمة ديناميكيًا ويجب عدم تعديلها مطلقًا.

أداة إنشاء عناوين URL في Google Play

استخدِم الأداة أدناه لإنشاء عناوين URL لقياس الحملات على Google Play.