ایجاد CPID

GTAF از کلید کاربر برای شناسایی مشترک هنگام برقراری ارتباط با DPA استفاده می کند. برنامه هایی که به MSISDN کاربر دسترسی دارند می توانند از آن به عنوان user_key استفاده کنند. از سوی دیگر، برنامه هایی که به MSISDN دسترسی ندارند، نیاز به ایجاد شناسه طرح حامل (CPID) بدون کشف MSISDN کاربر دارند. در ادامه، مکانیسمی را که یک CPID را ایجاد می کند، شرح می دهیم.

جریان تماس CPID

شکل 2: جریان فراخوانی برای ایجاد CPID.

  1. یک برنامه Google در UE از یک API داخلی Google برای بازیابی URL نقطه پایانی CPID از GTAF استفاده می کند. اپراتور با استفاده از آدرس IP عمومی مشتری و MCC+MNC سیم کارت فعال شناسایی می شود. در مورد MVNO ها، گوگل از SPN و GID1 برای تعیین MVNO استفاده می کند
  2. مشتری یک درخواست HTTP GET به نقطه پایانی CPID صادر می کند. اپراتور ممکن است از ارسال درخواست از طریق HTTPS پشتیبانی کند.
  3. اپراتور ممکن است از تابع Deep Packet Inspection خود برای شناسایی درخواست و تزریق شماره تلفن کاربر به درخواست به عنوان یک هدر HTTP استفاده کند.
  4. نقطه پایانی CPID درخواست را دریافت می‌کند، CPID را می‌سازد، و CPID را با زمان حیات (TTL) به UE برمی‌گرداند که نشان می‌دهد UE برای چه مدت می‌تواند از این CPID استفاده کند.

اپراتور همچنین ممکن است از آدرس های IP به جای نام دامنه در URL نقطه پایانی CPID استفاده کند، اگر ترجیح داده شود. آدرس‌های IP ممکن است در فضای آدرس خصوصی باشند، اما باید توسط مشتریان Google در داخل شبکه اپراتورها قابل دسترسی باشند.

اپراتور باید اطلاعات زیر را به عنوان بخشی از فرآیند سوار شدن به Google ارائه دهد:

  1. CPID_URL که برنامه‌ها برای دریافت CPID با آن تماس خواهند گرفت. یک CPID_URL اجباری است، اما اپراتور می‌تواند چندین URL را برای افزایش دسترسی ارائه کند.
  2. فهرست پیشوندهای IP که اپراتور دارد و کد کشور تلفن همراه (MCC) و کد(های) شبکه تلفن همراه (MNC) که اپراتور می خواهد به CPID_URL های ارائه شده نگاشت شود. اگر اپراتور از SPN یا GID1 برای تشخیص MVNOها در شبکه خود استفاده کند، اپراتور باید این اطلاعات را نیز ارائه دهد. همانطور که در مرحله 1 شکل 2 نشان داده شده است، Google از این اطلاعات برای تطبیق مشتریان با نقاط پایانی CPID مربوطه استفاده خواهد کرد.

فرمت درخواست این است: GET CPID_URL به دلایل قدیمی، نقطه پایانی CPID باید بتواند درخواستی مانند موارد زیر را پشتیبانی کند:

GET CPID_URL?app={app_id}

نقطه پایانی CPID می‌تواند پارامتر URL {app_id} را هنگام ایجاد CPID نادیده بگیرد. اما، باید بتواند درخواستی را که حاوی پارامتر است رسیدگی کند.

درخواست به نقطه پایانی CPID ممکن است شامل سرصفحه Accept-Language باشد. اگر هدر گنجانده شده باشد، رشته‌های قابل خواندن توسط انسان در به‌روزرسانی‌هایی که DPA با استفاده از Mobile Data Plan Sharing API ارسال می‌کند، باید از تنظیمات ارائه شده در درخواست CPID استفاده کند.

هر بار که مشتری یک درخواست GET CPID_URL صادر می کند، باید یک CPID جدید دریافت کند. اگر ایجاد CPID با موفقیت انجام شود، نقطه پایانی CPID باید یک پاسخ 200 OK را ارائه دهد. بدنه پاسخ باید شامل یک نمونه از CPDRsponse باشد.

{
    "cpid": "<CPID_string>",
    "ttlSeconds": 2592000
}

CPID برگشتی باید برای ttlSeconds ثانیه معتبر باشد، حتی اگر یک مشترک پس از آن CPID های دیگری را درخواست کرده باشد. Google توصیه می‌کند برای بهترین تجربه کاربری، از مقدار TTL 30 روزه استفاده کنید اما نه کمتر از 14 روز. GTAF در تماس‌های بعدی با DPA، CPID را در هر RFC2396 رمزگذاری می‌کند.

تولید CPID

روش توصیه شده برای نقطه پایانی CPID برای ایجاد یک CPID این است:

CPID_string = Base64(AES(MSISDN + TimeStamp + language, secret))

نقطه پایانی CPID MSISDN، زبان ارسال شده توسط کلاینت در هدر Accept-Language و یک مهر زمانی با وضوح بالا را به هم متصل می کند و آن را از طریق AES با استفاده از کلید secret رمزگذاری می کند. مهر زمانی باید با زمانی که CPID منقضی می شود مطابقت داشته باشد. خروجی رمزگذاری شده Base64 کدگذاری شده است. علاوه بر این، زمانی که CPID در یک URL استفاده می شود، باید برای مدیریت کاراکترهای خاص (/+=) مورد استفاده در Base64 کدگذاری شده باشد. به ویژه هنگامی که GTAF با DPA تماس می گیرد یا زمانی که DPA با API اشتراک گذاری طرح داده تلفن همراه تماس می گیرد، CPID باید با URL رمزگذاری شده باشد.

بسته به موقعیت یک اپراتور خاص، ممکن است اجرای نقطه پایانی CPID غیر ضروری باشد. یک چالش خاص که اغلب با آن مواجه شده است دسترسی به MSISDN در نقطه پایانی CPID است. ما خوشحالیم که درس های آموخته شده توسط اپراتورها را به اشتراک می گذاریم. لطفا در صورت مواجهه با هر گونه چالش با ما تماس بگیرید.

ذخیره سازی CPID

یک CPID که با استفاده از مکانیسم توضیح داده شده در بالا ایجاد می شود، لازم نیست در یک پایگاه داده ذخیره شود. اطلاعات مربوطه برای رسیدگی به تماس ها با DPA را می توان از CPID به دست آورد.

  1. هنگامی که DPA برای وضعیت طرح یا پیشنهادات تماسی از GTAF دریافت می کند، MSISDN را می توان با رمزگشایی CPID و استخراج MSISDN استخراج کرد.
  2. زمان انقضای CPID را می توان با رمزگشایی CPID و سپس استخراج مهر زمانی انقضا بدست آورد.

در دسترس بودن و ظرفیت مورد نیاز

اگر مشتریان نتوانند یک CPID را بازیابی کنند، نمی توانند به هیچ اطلاعاتی از Mobile Data Plan API دسترسی داشته باشند. به همین دلیل، اپراتور باید اقدامات لازم را برای اطمینان از در دسترس بودن نقطه پایانی CPID انجام دهد. چنین اقداماتی شامل داشتن چندین نمونه از توابع نقطه پایانی CPID و DPI و داشتن افزونگی فیزیکی، سایت و شبکه برای هر دو عملکرد است و اطمینان از کافی بودن منابع و ظرفیت سیستم. علاوه بر این، نقطه پایانی CPID و همچنین تابع DPI که هدر را تزریق می‌کند باید ظرفیت کافی برای مدیریت بار تمام مشتریان Google درخواست کننده CPID داشته باشد. نقطه پایانی CPID می تواند از مقادیر بزرگتر در فیلد ttlSeconds استفاده کند تا فرکانس تولید CPID را کاهش دهد.

موارد خطا

اگر خطایی رخ دهد، نقطه پایانی CPID باید یک خطای HTTP را با بدنه پاسخی که باید حاوی نمونه ای از ErrorResponse باشد، برگرداند. یک پیام خطای خوب شامل اطلاعاتی است که می تواند به رفع اشکال علت خطا کمک کند. به عنوان مثال، در مورد CPID منقضی شده، از جمله تولید CPID و زمان انقضا به ما کمک می کند تا تأیید کنیم که نقطه پایانی CPID طبق طراحی کار می کند.

{
    "errorMessage": "<error message>",
    "cause": "USER_ROAMING"
}

بسته به سناریو، نقطه پایانی CPID باید موارد زیر را برگرداند:

  1. اگر درخواست CPID برای کاربری دریافت شود که به شبکه اپراتور تعلق ندارد (به عنوان مثال، کاربری متعلق به اپراتور دیگری اما در شبکه ای که توسط این نقطه پایانی CPID سرویس می شود رومینگ می کند) یا اشتراک گذاری اطلاعات طرح داده با Google را انتخاب نکرده است، نقطه پایانی CPID باید کد وضعیت HTTP 403 را با USER_ROAMING، USER_OPT_OUT یا INELIGIBLE_FOR_SERVICE به عنوان دلیل برگرداند.
  2. اگر درخواست CPID با شماره تلفن نامعتبر دریافت شود، نقطه پایانی CPID باید HTTP 400 را با دلیل خطای INVALID_NUMBER برگرداند.
  3. اگر درخواست به نقطه پایانی CPID به شکل دیگری نادرست باشد، نقطه پایانی CPID باید HTTP 400 را با ERROR_CAUSE_UNSPECIFIED به عنوان علت برگرداند.
  4. برای سایر دلایل خطا، هر کد خطای HTTP سازگار قابل قبول است. به طور خاص، HTTP 500 یک دلیل خطای مناسب برای هر گونه خرابی داخلی در نقطه پایانی CPID است.