企业内部开发 客户端API 移动端SDK 企业微信登录 iOS应用
iOS应用

目录

  • iOS接入指南
  •       创建应用
  •       下载企业微信终端SDK文件
  •       搭建开发环境
  •       在代码中使用SDK进行初始化注册
  •       接入企业微信登录
  •       通过code获取用户信息
  • iOS接入指南

    接入说明:
    任何需要调用企业微信API的应用,都需要先在企业微信管理后台创建一个应用,设置完成后,即可使用对应的功能。
    不允许跨企业使用,即仅支持企业自己的app使用。

    创建应用

    1. 管理员登录企业微信管理后台,选择企业应用
    2. 选择已有应用或添加应用,进入应用详情页面。
    3. 选择“企业微信授权登录”,在设置界面填写iOS App的BundleId,设置完成后系统自动生成应用程序scheme

    下载企业微信终端SDK文件

    SDK文件包括 libWXWorkApi.a,WWKApi.h,WWKApiObject.h 三个。
    请前往 资源下载 下载最新SDK包sdk.zip

    注 :接入企业微信登录/分享 SDK的开发者,请先认真阅读《企业微信登录/分享SDK个人信息保护规则》,并确保对企业微信分享 SDK的接入使用情况符合上述规则的相关要求。

    下载包包含4个文件,其名称和含义分别是:
    WWKApi.h 定义SDK接口的头文件
    WWKApiObject.h 定义SDK接口用来进行参数传递的对象
    libWXWorkApi.a 第三方工程需要引用的SDK静态库文件
    demo.tar.gz 一个供参考的企业微信iOS端SDK使用的示例工程,这个工程介绍了当前版本SDK提供的所有接口的使用方法

    搭建开发环境

    1. 在XCode中建立你的工程。
    2. 将SDK文件中包含的 libWXWorkApi.aWWKApi.hWWKApiObject.h 三个文件添加到你所建的工程中。具体实现可参考 资源下载 页面中提供的SDK Sample Demo工程(下载sdk.zip压缩包后,解压其中的demo.tar.gz即为一个供参考的企业微信iOS端SDK使用的示例工程,这个工程介绍了当前版本SDK提供的所有接口的使用方法)。
    3. 在你的工程文件中选中Search Paths,并添加 libWXWorkApi.aWWKApi.hWWKApiObject.h,文件所在位置。
    4. 在XCode中,选择你的工程设置项,选中“TARGETS”一栏,在“Info”标签栏的“URL Types”添加“URL Schemes”,其内容为你所注册的应用程序将获得应用程序IDscheme
    5. 在你需要使用企业微信终端API的文件中 import WWKApi.h 并增加 WWKApiDelegate 协议。
    #import "AppDelegate.h"
    #import "WWKApi.h"
    
    @interface AppDelegate () <WWKApiDelegate>
    
    @end
    
    @implementation AppDelegate
    
    @end

    在代码中使用SDK进行初始化注册

    1. 要使你的程序启动后企业微信终端能响应你的程序,必须在代码中向企业微信终端注册你的scheme。(如下面代码所示,在 AppDelegate 的 didFinishLaunchingWithOptions 函数中向企业微信注册id)。
      参数说明
      registerApp : 必填字段 用户填写第三方应用Bundleid完成上述注册流程后,系统根据corpId(企业ID 见下描述)与agentId(应用ID 见下描述)计算得到的一个scheme字符串。用于企业微信完成SSO登录流程后回调返回用户的第三方应用
      corpId: 必填字段 用户登录企业管理页面的时候在 “我的企业” 页面会得到一个corpId,这个corpid即为需要填在这里的企业ID
      agentId: 必填字段 当用户为自己企业新加一个第三方iOS应用的时候,系统会为每个iOS应用分配不同的企业内部唯一的应用ID
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
        /*! @brief 调用这个方法前需要先到管理端进行注册 走管理端的注册方式
         *
         * 在管理端通过注册(可能需要等待审批),获得schema+corpid+agentid
         * @param registerApp 第三方App的Scheme
         * @param corpId 第三方App所属企业的ID
         * @param agentId 第三方App在企业内部的ID
         */
        [WWKApi registerApp:@"wwauth700000a5f2191000014" corpId:@"ww700000a5f2191" agentId:@"1000014"];
        return YES;
    }

    2.重写AppDelegate的handleOpenURL和openURL方法,第三方iOS App需要在这两个方法中调用SDK的handleOpenURL接口方法,让SDK有机会在第三方App内部处理SSO结果返回给第三方iOS App后的后续处理工作

    - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(nullable NSString *)sourceApplication annotation:(id)annotation {
        return [self handleOpenURL:url sourceApplication:sourceApplication];
    }
    
    - (BOOL)handleOpenURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication {
        return [WWKApi handleOpenURL:url delegate:self];
    }

    3.现在,你的程序要实现和企业微信终端交互的具体请求与回应,因此需要实现WWKApiDelegate协议的两个方法。第三方iOS App可以根据自身需求实现这两个方法

    // 如果第三方程序向企业微信发送了sendReq的请求,那么onResp会被回调。sendReq请求调用后,会切到企业微信终端程序界面。
    - (void)onResp:(WWKBaseResp *)resp {
    }
    // onReq是企业微信终端向第三方程序发起请求,要求第三方程序响应。第三方程序响应完后必须调用sendRsp返回。在调用sendRsp返回时,会切回到企业微信终端程序界面。
    -(void) onReq:(WWKBaseReq*)req {
    }

    具体在此两方法中所要完成的内容由你定义,具体可参考企业微信开发工具包中的SDK Sample Demo源码。

    接入企业微信登录

    使用SDK中的企业微信登录功能,获取企业微信用户信息。

    // 其中req参数为WWKSendMessageReq类型 根据发送的消息类型不同需要设置不同的req变量
    -(BOOL) sendReq:(BaseReq*)req
    - (IBAction)SSO:(id)sender {
        WWKSSOReq *req = [[WWKSSOReq alloc] init];
        // state参数为这次请求的唯一标示,客户端需要维护其唯一性。SSO回调时会原样返回
        req.state = @"adfasdfasdf23412341fqw4df14t134rtflajssf8934haioefy";
        [WWKApi sendReq:req];
    }

    需要特别指出的是,使用了SSO接口进行登录的程序需要在 handleOpenURL 函数中处理来自企业微信的回调,企业微信返回的是获取用户信息的一次性code,第三方app需要继续使用此code通过后端服务器换取用户的信息。

    通过code获取用户信息

    请求方式:GET(HTTPS
    请求地址:https://qyapi.weixin.qq.com/cgi-bin/user/getuserinfo?access_token=ACCESS_TOKEN&code=CODE

    参数说明:

    参数必须说明
    access_token调用接口凭证
    code通过成员授权获取到的code,每次成员授权带上的code将不一样,code只能使用一次,5分钟未被使用自动过期

     

    权限说明:
    跳转的域名须完全匹配企业内任一应用的可信域名。

    返回结果:

    {
       "errcode": 0,
       "errmsg": "ok",
       "UserId":"USERID",
    }
    
    参数说明
    UserId成员UserID

    出错返回示例:

    {
       "errcode": 40029,
       "errmsg": "invalid code"
    }
    
    上一篇
    概述
    下一篇
    Android应用