请求Body（BidRequest）

BidRequest 主要包括以下几个对象 request_id、api_ver、source_type、User、App、Device、Position、timeout，该结构体主要用来保存广告请求的所有信息

层级关系如下：

表格描述如下：

字段名称	类型	必填	描述	示例
request_id	string	是	请求ID，标志一次请求的唯一ID, 不可重复，推荐用UUID生成ID	request_id= e9de2c34db51f0bf850f76a7facadf4c
api_ver	string	是	请求的 API 版本，与文档的接入版本保持一致，比如说文档接入时是 2.1.12 那么 api_ver=2.1.12	api_ver = 2.1.12
source_type	string	是	流量类型：app	source_type = app
user	User	否	用户基本信息，详见 6.2.1. User 对象	见下述表格
app	App	是	媒体(应用)参数，用来保存媒体(应用)信息，详见 6.2.2. App 对象	见下述表格
device	Device	是	用户设备参数，用来保存收集到的当前设备的信息,详见 6.2.3. Device 对象	见下述表格
position	array Position	是	广告位(资源位)对象，在游可赢广告管理平台申请的资源位信息,详见 6.2.7. Position 对象	见下述表格
cooperation_ext	Cooperat ionExt	否	联运合作拓展字段,详见6.2.8. CooperationExt 对象	见下述表格
timeout	int32	否	超时时间设置，单位是 ms	timeout = 500

6.2.1. User#

User 主要用来保存用户的一些基本信息。

字段名称	类型	必填	描述	示例
id	string	否	用户对象id	id =bb5dfdc1948a40c4d
yob	int32	否	出生年月	yob = 199408
gender	string	否	用户性别	gender = 男
keywords	string	否	用户兴趣关键字	keywords = 数码产品
source_channel	string	否	用户来源渠道 1 其他 2 谷歌应用市场 3 快用应用商店 4 腾讯应用宝 5 小米应用商店 6 oppo应用商店 7 vivo应用商店 8 华为应用商店 9 优酷应用商店 10 官网 11 PP手机助手 12 91助手 13 iTools 14 易玩应用商店 15 360手机助手 16 联想乐商店 17 金山应用商店 18 海马应用商店 19 UC浏览器应用商店 20 搜狗手机助手 21 金立应用商店 22 魅族应用商店 23 豌豆荚	source_channel = 5

6.2.2. App#

App 主要用来保存当前请求的媒体(应用)信息，该信息主要来源于在游可赢广告管理平台申请的应用 id等，请保证请求信息与平台配置信息是一致的。

字段名称	类型	必填	描述	示例
app_id	int64	是	投放的流量主媒体 app_id，该ID来自于媒体在游可赢广告管理平台申请的媒体(应用)ID	app_id = 10055
app_ver	string	是	当前媒体(应用)的版本号，用来追踪媒体(应用)各版本的流量情况	app_ver = 1.3.2.0
app_pkg	string	是	媒体(应用)的包名	app_pkg = com.company-name.demo-app
personal_recommend_switch	int32	否	是否开启个性化推荐开关(1-开启,2-关闭)	personal_recommend_switch = 1

6.2.3. Device#

Device 主要用来保存收集到的当前用户的设备信息，该信息主要用来做用户标签、定向、特征工程等，帮助广告系统推送效果更好的广告，所以该对象里面的字段要求尽可能准确填写。

字段名称	类型	必填	描述	示例
ua	string	否	浏览器userAgent值	ua = Mozilla/5.hone; CPU iPhone OS 10_3 like Mac OS X) AppleWebKit/603.1.30 (KHTML, like Gecko) Mobile/14E277ua qapp qukan_ios qukan_version_31005000 iOS_DH_CPC_OICLK qapp
ip	string	是	客户端IP：请求公网出口IP，要求尽可能填写，不填会影响广告效果	ip = 203.205.141.119
ipv6	string	否	用户请求IPv6	ipv6 = 2001:0db8:3c4d:0015:0000:0000:1a2f:1a2b
language	string	否	系统语言 zh 中文 tc 繁体 en 英文 unknown 未知	language = zh
geo	Geo	否	设备地理位置对象	详见6.2.4. Geo
brand	string	是	设备制造商，例如 "apple"，"samsung" 小写处理	brand = huawei
model	string	是	设备型号, 例如 "iphone" 小写处理	model = mate40
os	string	是	系统类型, 填写"unknown", "iOS", "android"	os = android
osv	string	是	系统版本	osv = 10
width	int32	是	屏幕宽度，单位：像素px	width = 720
height	int32	是	屏幕高度，单位：像素px	height = 1280
orientation	string	是	屏幕方向 "horizontal"：横屏 "vertical"：竖屏 "unknown"：未知	orientation = horizontal
network	string	是	网络类型"unknown", "wifi", "2G", "3G", "4G", "5G"	network = 5G
carrier	string	是	映射关系： 46000 中国移动（GSM） 46001 中国联通（GSM） 46002 中国移动（TD-S） 46003 中国电信（CDMA） 46005 中国电信（CDMA） 46006 中国联通（WCDMA） 46007 中国移动（TD-S） 46011 中国电信（FDD-LTE） 46020 中国铁通 unknown 未知	carrier = 46000
devicetype	DeviceType	是	设备类型: 1 手机/平板，2 个人电脑，3 联网电视，4手机, 5平板 enum DeviceType { DEVICE_UNKNOWN = 0; PHONE_TABLET = 1; PC = 2; TV = 3; PHONE = 4; TABLET = 5; } 目前根据设备填写 4 或者 5即可	devicetype = 4
idfa	string	是	iOS设备号 idfa, 与 caid 必需填写一个，或者其 md5 值填一个请传入苹果idfa值。长度36位	idfa = 35718C64-4E4D-48CC-A3F2-A670D7CE5F13
idfa_md5	string	否	iOS设备号 idfa 的md5 值请传入32位小写md5值
imei	string	是	Android设备号 imei, 与 oaid 必需填写一个，或者其 md5 值填一个 imei长度为14-17，需要符合imei规则。长度为14，只能包含数字、abcdefABCDEF中的字符；长度为15、16、17时，只能包含数字	imei = 868384035256964
imei_md5	string	否	Android设备号 imei md5值请传入32位小写md5值
oaid	string	是	Android设备号 oaid , 与 imei 必需填写一个，或者其 md5 值填一个请传入符合信通院规定的oaid格式字符串。oaid长度14-64位，只能包含数字、abcdefABCDEF-中的字符	oaid = dafcfd3a-fffb-942c-e7e3-ff773deab71a
oaid_md5	string	否	Android设备号 oaid md5值请传入32位小写md5值
caid	string	是	iOS设备号 caid 与 idfa 必填一个，或者其 md5 值填一个请传入符合信通院规定的caid格式字符串。caid长度32位，只能包含数字、abcdefABCDEF中的字符	caid = bc7dfc7c52eeed0a4e9100420edb1aeb
caid_md5	string	否	iOS设备号caid md5 请传入32位小写md5值
android_id	string	否	安卓 id	android_id = 235f974ff73427a8
android_id_md5	string	否	安卓 id md5
init_caid	Caid	否	iOS 设备填写，此字段用于生成 caid 信息（只要填写了，我们就认为要使用该字段生成caid） Caid结构体详见6.2.5	Caid结构体详见6.2.5
qimei36	string	否	传值了qimei36的，会依据qimei36的映射关系替换掉相应的设备号

6.2.3.1. 注意事项#

1、设备ID号传值规则

1）若设备为iOS设备，则 idfa、idfa_md5、caid、caid_md5、init_caid 必填其中之一，否则不会返回广告；若选择caid相关参数，推荐填写 init_caid以提高准确性。（若 caid 和 init_caid 均填写，则系统会优先使用 init_caid）；

2）若设备为Android设备，则 imei、imei_md5、oaid、oaid_md5 必填其中之一，否则不会返回广告；

3）请按照字段说明传入正确的设备号获取广告，否则不会返回广告。

6.2.4. Geo#

Geo 主要是用来采集用户的位置信息，用于分地域精准投放

字段名称	类型	必填	描述	示例
lat	double	是	纬度信息, 取值范围-90.0到+90.0，负值表示南纬	lat = 22.837496
lon	double	是	经度信息, 取值返回-180.0到+180.0，负值表示西经	lon = 114.992036
type	LocationType	否	位置信息的源, 当传递lat/lon的时候推荐填充 enum LocationType { LOCATION_UNKNOWN = 0; GPS_LOCATION = 1; IP = 2; USER_PROVIDED = 3; }	type = 2
country	string	否	国家码, 使用 ISO-3166-1-alpha-3	country = CHN
region	string	否	区域码, 使用 ISO-3166-2;	region = zho
city	string	否	城市码, 使用联合国贸易与运输位置码

6.2.5. Caid#

字段名称	类型	必填	描述	示例
boot_time_in_sec	string	是	设备启动时间	1595643553
country_code	string	是	国家	CN
language	string	是	语言	zh-Hans-CN
device_name	string	是	设备名称（小写32位）	40997489371e54e1aadb212f9367065c
model	string	是	设备Model	D22AP
system_varsion	string	是	系统版本	14.0
machine	string	是	设备Machine	iPhone11,8
carrier_info	string	是	运营商	中国移动
memory	string	是	物理内存容量	3955589120
disk	string	是	硬盘容量	63900340224
sys_file_time	string	是	系统更新时间	1595214620.383940
time_zone	string	是	时区	28800

6.2.6. Caid 取值伪代码#

6.2.6.1. 设备启动时间 bootTimeInSec#

static time_t bootSecTime(){
    struct timeval boottime;
    size_t len = sizeof(boottime);
    int mib[2] = { CTL_KERN, KERN_BOOTTIME };
    if( sysctl(mib, 2, &boottime, &len, NULL, 0) < 0 ) {
        return 0;
    }
    return boottime.tv_sec;
}

+(NSString *)bootTimeInSec
{
    return [NSString stringWithFormat:@"%ld",bootSecTime()];
}

6.2.6.2. 国家 countryCode#

+(NSString *)countryCode
{
    NSLocale *locale = [NSLocale currentLocale];
    NSString *countryCode = [locale objectForKey:NSLocaleCountryCode];
    return countryCode;
}

6.2.6.3. 语言 language#

+(NSString *)language {
    NSString *language;
    NSLocale *locale = [NSLocale currentLocale];
    if ([[NSLocale preferredLanguages] count] > 0) {
        language = [[NSLocale preferredLanguages]objectAtIndex:0];
    } else {
        language = [locale objectForKey:NSLocaleLanguageCode];
    }
    return language;
}

6.2.6.4. 设备名称 deviceName#

+(NSString *)deviceName
{
    NSString *deviceName = [[UIDevice currentDevice] name];
    if ([deviceName length] == 0) {
        return nil;
    }
    
    NSString *data = [deviceName dataUsingEncoding:NSUTF8StringEncoding];
    unsigned char digist[CC_MD5_DIGEST_LENGTH];
    CC_MD5(dataBytes, (uint)data.length, digist);
    NSMutableString *result = [NSMutableString string];
    for (NSInteger i = 0; i < CC_MD5_DIGEST_LENGTH; i++) {
        [result appendFormat:@"%02x", digist[i]];
    }
    return result;  
}

6.2.6.5. 系统版本 systemVersion#

+(NSString *)systemVersion
{
    return [[UIDevice currentDevice] systemVersion];
}

6.2.6.6. 设备Machine machine#

+(NSString *)machine
{
    NSString *machine = getSystemHardwareByName(SIDFAMachine);
    return machine == nil ? @"" : machine;
}

static const char *SIDFAMachine = "hw.machine";
static NSString *getSystemHardwareByName(const char *typeSpecifier) {
    size_t size;
    sysctlbyname(typeSpecifier, NULL, &size, NULL, 0);
    char *answer = malloc(size);
    sysctlbyname(typeSpecifier, answer, &size, NULL, 0);
    NSString *results = [NSString stringWithUTF8String:answer];
    free(answer);
    return results;
}

6.2.6.7. 运营商 carrierInfo#

+(NSString* )carrierInfo {
    #if TARGET_IPHONE_SIMULATOR
        return @"SIMULATOR";
    #else
    static dispatch_queue_t _queue;
    static dispatch_once_t once;
    dispatch_once(&once, ^{_queue = dispatch_queue_create([[NSString stringWithFormat:@"com.carr.%@", self] UTF8String], NULL);});
    block NSString * carr = nil;
    dispatch_semaphore_t semaphore = dispatch_semaphore_create(0);
    dispatch_async(_queue, ^(){
        CTTelephonyNetworkInfo *info = [[CTTelephonyNetworkInfo alloc] init];
        CTCarrier *carrier = nil;
        if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 12.1)
        { 
            if ([info respondsToSelector:@selector(serviceSubscriberCellularProviders)]) {
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wunguarded-availability-new"
                NSArray *carrierKeysArray = [info.serviceSubscriberCellularProviders.allKeys sortedArrayUsingSelector:@selector(compare:)];
                carrier = info.serviceSubscriberCellularProviders[carrierKeysArray.firstObject];
                if (!carrier.mobileNetworkCode) {
                    carrier = info.serviceSubscriberCellularProviders[carrierKeysArray.lastObject];
                }
#pragma clang diagnostic pop
            }
        }
        if(!carrier)
        { #pragma clang diagnostic
        push
        #pragma clang diagnostic ignored "-Wdeprecated-declarations"
            carrier = info.subscriberCellularProvider;
        #pragma clang diagnostic pop
        }
        
        if (carrier != nil) {
            NSString *networkCode = [carrier mobileNetworkCode];
            NSString *countryCode = [carrier mobileCountryCode];
            if (countryCode && [countryCode isEqualToString:@"460"] && networkCode) {
                if ([networkCode isEqualToString:@"00"] ||
                [networkCode isEqualToString:@"02"] ||
                [networkCode isEqualToString:@"07"] ||
                [networkCode isEqualToString:@"08"]) {
                    carr= @"中国移动";
                }
                if ([networkCode isEqualToString:@"01"]
                || [networkCode isEqualToString:@"06"]
                || [networkCode isEqualToString:@"09"]){ 
                    carr= @"中国联通";
                }
                if ([networkCode isEqualToString:@"03"]
                || [networkCode isEqualToString:@"05"]
                || [networkCode isEqualToString:@"11"]){ 
                    carr= @"中国电信";
                }
                if ([networkCode isEqualToString:@"04"]){ 
                    carr= @"中国卫通";
                }
                if ([networkCode isEqualToString:@"20"]){ 
                    carr= @"中国铁通";
                }
            }else {
                carr = [carrier.carrierName copy];
            }
        }
        
        if (carr.length <= 0){ 
            carr =@"unknown";
        }
        dispatch_semaphore_signal(semaphore);
    });

    dispatch_time_t t = dispatch_time(DISPATCH_TIME_NOW, 0.5* NSEC_PER_SEC);
    dispatch_semaphore_wait(semaphore, t);
    return [carr copy];
#endif
}

6.2.6.8. 物理内存容量 memory#

+ (NSString *) memory
{
    return [NSString stringWithFormat:@"%lld", [NSProcessInfo processInfo].physicalMemory];
}

6.2.6.9. 硬盘容量 disk#

+(NSString *)disk
{
    int64_t space = -1;
    NSError *error = nil;
    NSDictionary *attrs = [[NSFileManager defaultManager]
    attributesOfFileSystemForPath:NSHomeDirectory() error:&error];
    if (!error) {
    space = [[attrs objectForKey:NSFileSystemSize] longLongValue];
    }
    
    if(space < 0){ 
        space = -1;
    }
    return [NSString stringWithFormat:@"%lld",space];
}

6.2.6.10. 系统更新时间 sysFileTime#

+(NSString *)sysFileTime
{ 
    NSString *result = nil;
    NSString *information = @"L3Zhci9tb2JpbGUvTGlicmFyeS9Vc2VyQ29uZmlndXJhdGlvblBy
    b2ZpbGVzL1B1YmxpY0luZm8vTUNNZXRhLnBsaXN0";
    NSData *data=[[NSData alloc]initWithBase64EncodedString:information options:0]
    ;
    NSString *dataString = [[NSString alloc]initWithData:data encoding:NSUTF8Strin
    gEncoding];
    NSError *error = nil;
    NSDictionary *fileAttributes = [[NSFileManager defaultManager]
    attributesOfItemAtPath:dataString error:&error];
    if (fileAttributes) {
        id singleAttibute = [fileAttributes objectForKey:NSFileCreationDate];
        if ([singleAttibute isKindOfClass:[NSDate class]]) {
            NSDate *dataDate = singleAttibute;
            result = [NSString stringWithFormat:@"%f",[dataDate timeIntervalSince1970]];
        }
    }
    return result;
}

6.2.6.11. 设备Model model#

+(NSString *)model
{
    NSString *model = getSystemHardwareByName(@"hw.model");
    return model == nil ? @"" : model;
}

6.2.6.12. 时区 timeZone#

+ (NSString *) timeZone
{
    NSInteger offset = [NSTimeZone systemTimeZone].secondsFromGMT;
    return [NSString stringWithFormat:@"%ld",(long)offset];
}

6.2.7. Position#

Position 主要用来保存当前请求的资源位信息，该信息主要来源于游可赢广告管理平台平台申请的广告位(资源位) ID,根据我们的广告形式，填写合适的广告数量以及何种激励形式的广告请求。

支持一次广告请求一个资源位、一次请求多个广告。

字段名称	类型	必填	描述	示例
pos_id	int64	是	广告位(资源位)id	pos_id = 10069
ad_count	int32	是	所需返回广告数量	ad_count = 1
bidfloor	int32	否	本次展示的最低竞拍价格，以CPM表示，单位: 分	bidfloor = 1000

6.2.8. CooperationExt#

CooperationExt 用于传输联运合作的拓展字段。

字段名称	类型	必填	描述	示例
traffic_type	array int32	否	流量类型： 0 - 竞价 -1 - 余量 5 - 合约	[0,-1,5]