افزودن دکمه «ذخیره در Drive»

دکمه «ذخیره در Drive» به کاربران امکان می‌دهد فایل‌ها را از وب‌سایت شما در Drive ذخیره کنند. برای مثال، فرض کنید وب‌سایت شما چندین دفترچه راهنما (PDF) را فهرست می‌کند که کاربران می‌توانند بارگیری کنند. دکمه «ذخیره در Drive» را می‌توان در کنار هر دفترچه راهنما قرار داد تا کاربران بتوانند دفترچه‌های راهنما را در My Drive خود ذخیره کنند.

وقتی کاربر روی دکمه کلیک می‌کند، فایل از منبع داده بارگیری می‌شود و با دریافت داده‌ها، در Google Drive بارگذاری می‌شود. چون بارگیری در بافت مرورگر کاربر انجام می‌شود، این فرایند به کاربر اجازه می‌دهد تا کنش ذخیره کردن فایل‌ها را بااستفاده از جلسه مرورگر ایجادشده‌اش اصالت‌سنجی کند.

مرورگرهای پشتیبانی‌شده

دکمه «ذخیره در Drive» از این مرورگرها پشتیبانی می‌کند.

افزودن دکمه «ذخیره در Drive» به صفحه

برای ایجاد نمونه‌ای از دکمه «ذخیره در Drive»، اسکریپت زیر را به صفحه وب خود اضافه کنید:

<script src="https://apis.google.com/js/platform.js" async defer></script>
<div class="g-savetodrive"
   data-src="//example.com/path/to/myfile.pdf"
   data-filename="My Statement.pdf"
   data-sitename="My Company Name">
</div>

مکان:

  • class پارامتری الزامی است که اگر از برچسب HTML استاندارد استفاده می‌کنید، باید روی g-savetodrive تنظیم شود.

  • data-src پارامتری الزامی است که حاوی نشانی وب فایلی است که باید ذخیره شود.

    • نشانی‌های وب می‌توانند مطلق یا نسبی باشند.
    • نشانی وب data-src می‌تواند از همان دامنه، زیردامنه، و پروتکلی ارائه شود که دکمه در آن میزبانی می‌شود. باید از پروتکل‌های منطبق بین صفحه و منبع داده استفاده کنید.
    • شناسه منبع یکسان داده و نشانی‌های وب file:// پشتیبانی نمی‌شود.
    • به‌دلیل خط‌مشی همان مبدأ مرورگر، این نشانی وب باید از همان دامنه‌ای ارائه شود که صفحه روی آن قرار دارد، یا بااستفاده از «هم‌رسانی منبع میان‌مبدئی» (CORS) قابل‌دسترسی باشد. اگر دکمه و منبع در دامنه‌های مختلفی قرار دارند، به مدیریت دکمه‌ها و منابع در دامنه‌های مختلف.(#domain) مراجعه کنید.
    • برای ارائه فایل وقتی صفحه یکسان توسط http و https ارائه می‌شود، منبع را بدون پروتکل مشخص کنید، مثلاً data-src="//example.com/files/file.pdf"، که از پروتکل مناسب براساس نحوه دسترسی به صفحه میزبان استفاده می‌کند.

  • data-filename پارامتر الزامی‌ای است که حاوی نام استفاده‌شده برای فایل ذخیره‌شده است.

  • data-sitename پارامتری الزامی است که حاوی نام وب‌سایت ارائه‌دهنده فایل است.

می‌توانید این مشخصه‌ها را روی هر عنصر HTML قرار دهید. بااین‌حال، رایج‌ترین عناصر مورداستفاده div،‏ span، یا button هستند. هرکدام از این عناصر هنگام بار شدن صفحه کمی متفاوت نمایش داده می‌شوند، زیرا مرورگر عنصر را قبل‌از اینکه جاوا اسکریپت «ذخیره در Drive» عنصر را دوباره پرداز بزند، پرداز می‌زند.

این اسکریپت باید بااستفاده از پروتکل HTTPS بار شود و می‌تواند از هر نقطه‌ای در صفحه بدون محدودیت گنجانده شود. همچنین می‌توانید برای بهبود عملکرد، اسکریپت را به‌صورت ناهمگام بار کنید.

استفاده از چند دکمه در یک صفحه

می‌توانید چندین دکمه «ذخیره در Drive» را در یک صفحه قرار دهید. برای مثال، ممکن است دکمه‌ای در بالا و پایین صفحه‌ای طولانی داشته باشید.

اگر پارامترهای data-src و data-filename برای چند دکمه یکسان باشد، ذخیره کردن از یک دکمه باعث می‌شود همه دکمه‌های مشابه اطلاعات پیشرفت یکسانی را نمایش دهند. اگر روی چند دکمه مختلف کلیک شود، به‌ترتیب ذخیره می‌شوند.

مدیریت دکمه‌ها و منابع در دامنه‌های مختلف

اگر دکمه «ذخیره در Drive» در صفحه‌ای جدا از منبع داده قرار دارد، درخواست ذخیره فایل باید از هم‌رسانی منبع میان‌مبدئی (CORS) برای دسترسی به منبع استفاده کند. CORS سازوکاری است که به برنامه وب در یک دامنه اجازه می‌دهد به منابع سرور در دامنه‌ای دیگر دسترسی پیدا کند.

برای مثال، اگر دکمه «ذخیره در Drive» در صفحه‌ای در http://example.com/page.html قرار داده شده باشد و منبع داده به‌صورت data-src="https://otherserver.com/files/file.pdf" مشخص شده باشد، دکمه نمی‌تواند به فایل PDF دسترسی پیدا کند، مگر اینکه مرورگر بتواند از CORS برای دسترسی به منبع استفاده کند.

نشانی وب data-src می‌تواند از دامنه دیگری ارائه شود اما پاسخ‌های سرور HTTP باید از درخواست‌های HTTP OPTION پشتیبانی کند و سرایندهای ویژه HTTP زیر را دربرگیرد:

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Range
Access-Control-Expose-Headers: Cache-Control, Content-Encoding, Content-Range

Access-Control-Allow-Origin می‌تواند مقدار * داشته باشد تا CORS را از هر دامنه‌ای مجاز کند یا می‌تواند دامنه‌هایی را که ازطریق CORS به منبع دسترسی دارند مشخص کند، مانند http://example.com/page.html. اگر سروری برای میزبانی محتوایتان ندارید، از Google App Engine استفاده کنید.

برای اطلاعات بیشتر، به اسناد سرور خود درباره نحوه فعال کردن CORS از مبدأ ارائه‌دهنده دکمه «ذخیره در Drive» مراجعه کنید. برای اطلاعات بیشتر درباره فعال کردن سرور برای CORS، به می‌خواهم پشتیبانی CORS را به سرورم اضافه کنم مراجعه کنید.

JavaScript API

جاوا اسکریپت دکمه «ذخیره در Drive» دو تابع ارائه‌دهنده دکمه را در فضای نام gapi.savetodrive تعریف می‌کند. اگر پرداز خودکار را غیرفعال کنید، باید یکی از این توابع را با تنظیم parsetags روی explicit فراخوانی کنید.

روش شرح
gapi.savetodrive.render(
container,
parameters
)		 محفظه مشخص‌شده را به‌عنوان ابزاره دکمه «ذخیره در Drive» ارائه می‌کند.
محتوی
محفظه‌ای که به‌عنوان دکمه «ذخیره در Drive» ارائه می‌شود. شناسه محتوی (رشته) یا خود عنصر DOM را مشخص کنید.
پارامترها
شیئی حاوی مشخصه‌های برچسب «ذخیره در Drive» به‌صورت جفت‌های کلید=مقدار، بدون پیشوندهای data-. برای مثال، {"src": "//example.com/path/to/myfile.pdf", "filename": "My Statement.pdf", "sitename": "My Company Name"}.
gapi.savetodrive.go(
opt_container
)		 همه برچسب‌ها و کلاس‌های «ذخیره در Drive» را در ظرف مشخص‌شده ارائه می‌کند. این تابع فقط باید زمانی استفاده شود که parsetags روی explicit تنظیم شده باشد، که ممکن است به دلایل عملکردی این کار را انجام دهید.
opt_container
محفظه حاوی برچسب‌های دکمه «ذخیره در Drive» برای ارائه. شناسه محتوی (رشته) یا خود عنصر DOM را مشخص کنید. اگر پارامتر opt_container حذف شود، همه برچسب‌های «ذخیره در Drive» در صفحه ارائه می‌شود.

نمونه جاوا اسکریپت «ذخیره در Drive» با بارگیری صریح

<!DOCTYPE html>
    <html>
      <head>
        <title>Save to Drive Demo: Explicit Load</title>
        <link rel="canonical" href="http://www.example.com">
        <script src="https://apis.google.com/js/platform.js" async defer>
          {parsetags: 'explicit'}
        </script>
      </head>
      <body>
        <div id="container">
          <div class="g-savetodrive"
             data-src="//example.com/path/to/myfile.pdf"
             data-filename="My Statement.pdf"
             data-sitename="My Company Name">
          <div>
        </div>
        <script type="text/javascript">
          gapi.savetodrive.go('container');
        </script>
      </body>
    </html>

نمونه جاوا اسکریپت «ذخیره در Drive» با پردازش صریح

    <!DOCTYPE html>
    <html>
      <head>
        <title>Save to Drive Demo: Explicit Render</title>
        <link rel="canonical" href="http://www.example.com">
        <script>
          window.___gcfg = {
            parsetags: 'explicit'
          };
        </script>
        <script src="https://apis.google.com/js/platform.js" async defer></script>
      </head>
      <body>
        <a href="javascript:void(0)" id="render-link">Render the Save to Drive button</a>
        <div id="savetodrive-div"></div>
        <script>
          function renderSaveToDrive() {
            gapi.savetodrive.render('savetodrive-div', {
              src: '//example.com/path/to/myfile.pdf',
              filename: 'My Statement.pdf',
              sitename: 'My Company Name'
            });
          }
          document.getElementById('render-link').addEventListener('click', renderSaveToDrive);
        </script>
      </body>
    </html>

بومی‌سازی دکمه «ذخیره در Drive»

اگر صفحه وب شما از زبان خاصی پشتیبانی می‌کند، متغیر window.___gcfg.lang را روی آن زبان تنظیم کنید. اگر تنظیم نشده باشد، از زبان Google Drive کاربر استفاده می‌شود.

برای مقادیر کد زبان دردسترس، فهرست کدهای زبان پشتیبانی‌شده را ببینید.

    <!DOCTYPE html>
    <html>
      <head>
        <title>Save to Drive Demo: Async Load with Language</title>
        <link rel="canonical" href="http://www.example.com">
      </head>
      <body>
        <div class="g-savetodrive"
             data-src="//example.com/path/to/myfile.pdf"
             data-filename="My Statement.pdf"
             data-sitename="My Company Name">
        </div>

        <script type="text/javascript">
          window.___gcfg = {
            lang: 'en-US'
          };
        </script>
        <script src = 'https://apis.google.com/js/platform.js' async defer></script>

      </body>
    </html>

عیب‌یابی

اگر هنگام بارگیری نشانی وب data-src با خطای XHR مواجه شدید، بررسی کنید که منبع واقعاً وجود داشته باشد و مشکل CORS نداشته باشید.

اگر فایل‌های بزرگ به ۲ مگابایت کوتاه می‌شوند، احتمالاً سرور شما Content-Range را نشان نمی‌دهد، که احتمالاً مشکل CORS است.