智能证件照 Android SDK集成文档

Android接入文档下载

可以通过两种方式来集成智能证件照 SDK：「快速集成」和「自定义集成」。

• 快速集成：使用 SDK 提供的界面，只需调用入口函数并注册回调
• 自定义集成：仅使用 SDK 提供的网络接口，自定义实现界面及相关逻辑

说明

以下教程针对 Android Studio

快速集成

快速集成使用 SDK 实现的相机、打分、抠图制作等预置界面，只需少量代码即可快速集成。

添加依赖

• 引入 SDK 相关的工程

一般项目中默认有 jCenter 的引用，若没有，在项目工程的 build.gradle 中加入 jCenter 的引用

    repositories {
        jcenter()
    }

在 dependencies 中添加：

    compile 'com.leqi:safelight:0.11.2'

集成到项目

初始化 SDK

在 Application 中添加

   public class MyApplication extends Application {
        @Override
        public void onCreate() {
            super.onCreate();
            Safelight.init(this);
        }
   }

并在 AndroidManifest.xml 中使用自定义的 Application

    <application
            android:name=".MyApplication"
            android:icon="@mipmap/ic_launcher"
            android:label="@string/app_name">
         ...
    </application>

或在 Activity 中初始化（需在调用前进行初始化）

    Safelight.init(getApplication());

使用

• 在需要用到的 Activity 中调用 SDK

    EntranceParam param = new EntranceParam(APP_KEY, APP_SECRET, SPEC_KEY, BACKDROP);
    //跳转SDK进行制作，传入activity，param，SafelightCallback
    Safelight.intentSDK(this, param, new SafelightCallback() {
            @Override
            public void onComplete(Bitmap bitmap, HashMap<String,Integer> score) {
                // 成功时的回调
                // bitmap 最终获得的照片
                // score 用户照片的各项分数
                // do something
            }

            @Override
            public void onError(String errorMessage) {
                // 发生错误时的回调
                // errorMessage 错误信息
                // do something
            }

            @Override
            public void onUserCancelled() {
                // 用户取消时的回调
                // do something
            }
        });

• 参数说明
  EntranceParam 为需要传入的参数
  APP_KEY, APP_SECRET 为在SDK后台申请密钥
  SPEC_KEY是将要生成的规格参数KEY,请在规格列表中查找 SPEC_KEY 参数
  BackDrop 为照片的背景
  BackDrop 构造方法 new Backdrop(int beginColor, int endColor)
  请在颜色列表中查找 begin_color 和 end_color 参数

自定义集成

对于需要自己定义 UI 样式的开发者，可以选择自行实现界面及跳转逻辑，仅使用 SDK 提供的证件照制作接口。

添加依赖

• 引入 SDK 相关的工程

一般项目中默认有 jCenter 的引用，若没有，在项目工程的 build.gradle中加入 jCenter 的引用

    repositories {
        jcenter()
    }

在dependencies中添加：

    compile 'com.leqi:safelight.filament:0.3.0'

集成到项目

初始化SDK

在 Application 中添加

   public class MyApplication extends Application {
        @Override
        public void onCreate() {
            super.onCreate();
            Safelight.init(this);
        }
   }

并在 AndroidManifest.xml 中使用自定义的 Application
或在 Activity 中初始化（需在调用前进行初始化）

Safelight.init(getApplication());

调用各个方法前需要先设置APP_KEY和APP_SECRET

    /**
     * @param appKey    在SDK后台申请的APP_KEY
     * @param appSecret 在SDK后台申请的APP_SECRET
     */
    Safelight.setParams(Keys.APP_KEY, Keys.APP_SECRET);

使用

以下方法为进行处理的具体流程，耗时较长，需要异步调用，在主线程中调用会抛出 IllegalStateException
1. 进行预处理，获取评分
2. 创建任务
3. 创建任务后，通过轮询获取任务结果
4. 获取任务结果后，创建订单
5. 根据订单状态进行处理，若订单需要支付，获取支付宝支付参数进行支付
6. 预付费用户且余额足够时，或支付宝支付成功后，查询订单状态，获取最终图片的 url

进行预处理，获取评分

    /**
     * @param bitmap 照片
     * @throws FaceNumException 人脸数量不对时抛出异常
     * @return 照片评分的Map Key为各评分项
     */
    HashMap<String, Integer> getPhotoScore(@NonNull Bitmap bitmap)

创建任务

    /**
     * @param specKey    规格key
     * @param beginColor 渐变开始颜色
     * @param endColor   渐变结束颜色
     * @return 任务id
     * @throws IOException
     * @throws IllegalStateException
     * @throws RequestException
     */
    String createTask(@NonNull String specKey, @Nullable Integer beginColor, @Nullable Integer endColor)

获取任务状态结果

    /**
     * 需要根据 TaskResult 中的 TaskState 进行处理
     * 如果状态为{PENDING,STARTED,RETRY}，需要轮询直到任务成功或者失败
     * @param taskId 任务ID
     * @return 任务状态结果
     * @throws IOException
     * @throws IllegalStateException
     * @throws RequestException
     */
    TaskResult getTaskResult(@NonNull String taskId)

TaskResult 中包含任务状态和预览 url

创建订单

    /**
     * 当创建任务成功，并获取预览url后调用
     * 根据taskId创建订单
     * @param taskId 任务ID
     * @return 创建的订单
     * @throws IOException
     * @throws IllegalStateException
     * @throws RequestException
     */
    Order createOrder(@NonNull String taskId)

Order 订单详情，包含订单状态等数据

获取支付宝支付参数

    /**
     * 创建订单后，若需要付款，则获取支付宝参数进行付款
     * @param orderNo 订单号
     * @return Alipay支付参数
     * @throws IOException
     * @throws IllegalStateException
     * @throws RequestException
     */
    AlipayParams getAlipayParams(@NonNull String orderNo)

获取最终图片url

获取最终图片 url 及订单实体，订单状态为已支付时，才可以获取最终图片的 url

    /**
     * 付款完成或预付费用户，获取最终图片的url
     * 若使用支付宝支付完成后状态仍为CREATED，可能需要轮询直到获取付款成功的结果
     * @param orderNo 订单号
     * @return url及订单实体，订单状态为已支付时，才可以获取最终图片的url
     * @throws IOException
     * @throws IllegalStateException
     * @throws RequestException
     */
    ImageResult getImageUrl(@NonNull String orderNo)

ImageResult 包含 Order 和最终图片的 url

具体见JavaDoc