نصب و راه‌اندازی SDK بکتوری

در این مستند قصد داریم به صورت گام‌به‌گام SDK بکتوری را به پروژه اندروید خود اضافه کنیم تا بتوانیم از امکانات آن برای پروژه‌های خود استفاده کنیم.

پیش‌نیازها

شما باید یک پروژه در بکتوری ساخته باشید.
محیط توسعه اندروید با نسخه حداقل 15 را راه‌اندازی کرده باشید.

توجه: در صورت امکان از نرم‌افزار Android Studio برای توسعه اپلیکیشن خود استفاده کنید. (ترجیح با نسخه 2.0 و یا بالاتر نرم‌افزار است، ولی نسخه‌های قدیمی‌تر نیز مشکلی ندارد). همچنین برای مدیریت کتابخانه‌ها و ساخت پروژه اندروید از ابزار Gradle استفاده کنید که به صورت پیش‌فرض بر روی Android Studio نصب می‌باشد.

نصب

ساده‌ترین راه برای نصب SDK بکتوری استفاده از ابزار Gradle است که به صورت پیشفرض در Android Studio وجود دارد. برای این کار کافیست:

در فایل build.gradle ماژول برنامه‌تان (به صورت پیشفرض با نام app) خط زیر را به قسمت dependencies اضافه کنید:

compile 'com.pegah.backtory:backtory-android-sdk:0.6.7' // put the latest version here

همچنین در قسمت repositories همان فایل (اگر چنین بخشی وجود ندارد، مطابق کد پایین، این بخش را ایجاد کنید) آدرس repository بکتوری را وارد کنید.

repositories {
    maven {
        url 'https://dl.bintray.com/pegah-backtory/maven/'
    }
}

به این ترتیب نصب SDK انجام شد.

چنانچه با ساخت پروژه gradle آشنایی ندارید، این لینک را مطالعه کنید.

راه‌اندازی

i. یک کلاس بسازید که از کلاس Application اندروید ارث‌بری کند. درون تابع ()onCreate آن، سرویس‌هایی از بکتوری را که ‌قصد استفاده از آن را دارید، مطابق تکه کد زیر برپا (setup) کنید.

// Extending android application to initialize backtory
public class MainApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // Initializing backtory
        BacktoryClient.init(KeyConfiguration.newBuilder().
            // Enabling User Services
            setAuthKeys("<X-Backtory-Authentication-Id>",
                        "<X-Backtory-Authentication-Key (Client)>").
            // Finalizing sdk
            build(), this);
    }
}

سرویس کاربران یک سرویس پایه است و برای استفاده از SDK بکتوری باید آن را مقداردهی اولیه (init) کنید (همان‌طور که در بالا مشاهده می‌کنید.) سایر سرویس‌های بکتوری اختیاری هستند و بسته به تنظیمات پروژه شما در پنل ممکن است فعال یا غیرفعال باشند. برای هر یک از این سرویس‌های اختیاری، در صورت فعال بودن، ‌میتوانید با صدا زدن توابع init مربوط به آن، آنها را راه‌اندازی کنید. برای مثال فرض کنید پروژه شما با مرکز بازی و سرویس رایانش کار می‌کند:

// Extending android application to initialize backtory
public class MainApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // Initializing backtory
        BacktoryClient.init(KeyConfiguration.newBuilder().
            setAuthKeys("<X-Backtory-Authentication-Id>",
                        "<X-Backtory-Authentication-Key (Client)>").
            // Enabling Cloud Code
            setCloudcodeKey("<Cloud-Code-Id>").
            // Enabling Game Center
            setGameKey("<X-Backtory-Game-Id>").
            // Finalizing sdk
            build(), this);
    }
}

توجه: هر یک از کلید‌ها و Idهای بالا را می‌توانید با ورود به داشبورد پروژه خود و کلیک بر روی بخش «کلیدها» استخراج کنید. دقت کنید که سرویس‌های «فایل» و «بلادرنگ» حتما باید در ابتدا فعال‌سازی شوند؛ در غیر این صورت، کلیدهای آن‌ها در بخش کلیدهای داشبورد مشاهده نخواهد شد. (برای فعال‌سازی این سرویس‌ها کافیست از طریق منوی پنل وارد سرویس مربوطه شوید تا در آن‌جا دکمه‌ی فعال‌سازی را مشاهده کنید.)

ii. کلاس Application خودتان را به AndroidManifest معرفی کنید. برای این کار در application tag یک attribute جدید با نام name اضافه کنید و آدرس Application خودتان را بدهید.

<application
    android:name=".MainApplication"
    ...
/>

iii. همه چیز آماده است. حال شما با مراجعه به مستندات هر یک از سرویس‌ها می‌توانید از آنها در محیط اندروید استفاده کنید.

راه اندازی در حالت عیب‌یابی (Debug mode)

با فعال کردن حالت عیب‌یابی، SDK اقدام به تولید یک سری گزارش (Log) از رویدادهایی که رخ می‌دهند می‌کند. محتوای درخواست و جواب های Http که توسط SDK ارسال و دریافت می‌شود، نمونه ای از این موارد است. جهت راه‌اندازی در حالت عیب‌یابی کد زیر را به کلاس Application خودتان به صورت زیر اضافه کنید:

public class MainApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        BacktoryClient.setDebugMode(BuildConfig.DEBUG);
        BacktoryClient.setLogLevel(LogLevel.Debug);         // Logs with debug priority
                                                // or higher. Includes network requests.
        BacktoryClient.init(...);
    }
}

توجه: برنامه خود را در حالت عیب‌یابی بر روی مارکت‌ها منتشر نکنید! در حالت عیب یابی SDK کندتر از حالت عادی است.

استفاده از Proguard

از نسخه‌ی 0.6.6 به بعد sdk بکتوری، قواعد Proguard به صورت خودکار همراه SDK به پروژه‌ی شما اضافه می‌شود. همچنین دقت کنید زمان فراخوانی تابع رایانش، کلاس‌هایی که برای ورودی و خروجی تابع تعریف می‌کنید، را باید با استفاده از دستور keepclassmembers از تغییرات مصون نگه دارید. به طور مثال فراخوانی تابع رایانش زیر را در نظر بگیرید:

BacktoryCloudCode.runInBackground("functionName", new MyCloudcodeReq(arg1, arg2),
    MyCloudcodeResponse.class, backtoryCallback);

در این حال می‌بایست هر دو کلاس MyCloudcodeReq و MyCloudcodeResponse را به فایل قواعد Proguard به صورت زیر اضافه کنید (آدرس کامل کلاس‎ها باید گذاشته شود.)

 -keepclassmembers class com.example.MyCloudcodeReq
-keepclassmembers class com.example.MyCloudcodeResponse

برنامه نمونه

تمام کدهای این مستند را می‌توانید در برنامه‌ی نمونه بکتوری در این آدرس مشاهده کنید.

لاگ تغییرات

شما همواره می‌توانید برای مشاهده‌ی آخرین ورژن SDK به این‌جا و برای مشاهده‌ی لاگ تغییرات هر ورژن به این‌جا مراجعه کنید.

نصب و راه‌اندازی SDK بکتوری - Android