跳到主要内容

5 LUA智能决策

5.1 系统函数列表​

出于安全及性能原因，RTA SaaS禁用了大量不必要的 LUA功能。以下为支持的全局函数列表。

函数名功能
next对table进行遍历
print打印信息（注：在生产环境中该函数被设置为不输出）
tonumber转换为数字
tostring转换为文本
type获取变量类型
unpack将table 的元素解包为多值返回

5.2 内置模块srta​

5.2.1 常量​

服务内置了名为 srta 的模块，提供了访问数据的功能及相关常量。

数据区

常量名称含义适用函数或变量
srta.DS_DID默认设备数据空间编号srta.get_dsdata()
srta.DS_WUID默认 WUID数据空间编号srta.get_dsdata()
srta.DS_GEO默认 就近数据空间编号srta.get_dsdata()
srta.DS_GEOIP默认 IP城市数据空间编号srta.get_dsdata()
srta.DS_GEOFAC默认 常住城市数据空间编号srta.get_dsdata()

字段区

常量名称含义适用函数或变量
srta.U8UINT8字段区dsdata
srta.U32UINT32字段区dsdata
srta.FLAGFLAG字段区dsdata

操作系统

常量名称含义适用函数或变量
srta.OS_UNKNOWN未知操作系统srta.get_os()
srta.OS_IOSiOSsrta.get_os()
srta.OS_ANDROIDAndroidsrta.get_os()
srta.OS_HARMONY鸿蒙srta.get_os()
srta.OS_OTHER其它操作系统srta.get_os()

站点集

常量名称含义适用函数或变量
srta.SITESET_UNION优量汇srta.get_siteset()
srta.SITESET_WECHAT微信srta.get_siteset()
srta.SITESET_XQXQsrta.get_siteset()
srta.SITESET_XS_NEWS腾讯新闻srta.get_siteset()
srta.SITESET_XS_VIDEO腾讯视频srta.get_siteset()

策略参数

常量名称含义适用函数或变量
srta.TARGETINFO_ENABLE策略参竞target_info
srta.TARGETINFO_CPC_PRICECPC出价target_info
srta.TARGETINFO_CPA_PRICECPA出价target_info
srta.TARGETINFO_USER_WEIGHT_FACTOR用户权重系数target_info
srta.TARGETINFO_CPC_FACTORCPC出价系数target_info
srta.TARGETINFO_DC_INFOSDCA标签信息（数组）target_info

DCA标签信息

常量名称含义适用函数或变量
srta.DC_TAG_NAMEDCA标签名称DCA数组元素
srta.DC_TAG_VALUEDCA标签值DCA数组元素

5.2.2 函数列表​

函数名功能
srta.get_dsdata获取数据空间数据
srta.get_targets获取需决策的策略ID列表
srta.get_apps获取App安装态(需授权)
srta.get_scores获取模型分(需授权)
srta.get_os获取终端操作系统
srta.get_siteset获取站点集ID
srta.get_expid获取实验分桶ID
srta.get_geo_nearest获取地理位置最近的数据

5.2.3 srta.get_dsdata函数​

返回的数据以 LUA Table 结构存在，定义如下

didData = srta.get_dsdata(srta.DS_DID) -- 获取设备数据

-- 以下为字段返回值示例
didData = {
    [1] = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, .... 0, 0, 0, 0, 0, 0, 0, 0},
    [2] = {0, 0, 0, 0, 0, 0, 0, 0},
    [3] = {false, false, false, false}
}

5.2.4 srta.get_targets函数​

返回的数据以 LUA Table 结构存在，定义如下

targets = srta.get_targets() -- 获取策略列表

-- 以下为字段返回值示例
targets = {"news", "music", "video_for_new"}

5.2.5 srta.get_apps函数​

一次可以获得多个App安装态，每个返回值为 true(已安装)/false(未安装)/nil(无权限或不可靠)中的一个状态

app1, app2, app3 = srta.get_apps(app1hash, app2hash, app3hash) -- 获取App安装态，可支持多个。

-- 以下为字段返回值示例
app1 = true
app2 = false
app3 = nil

5.2.6 srta.get_scores函数​

一次可以获得多个模型打分，每个返回值为数字/nil(无权限或不可靠)中的一个状态

score1, score2, score3 = srta.get_scores(model1, model2, model1) -- 获取模型分，可支持多个。
-- 以下为字段返回值示例
score1 = 0
score2 = 80
score3 = nil

5.2.7 srta.get_os函数​

获取终端的操作系统。返回值参考[系统常量]

os = srta.get_os() -- 获取终端操作系统

-- 以下为返回值示例
1 -- 代表iOS，可以用srta常量进行判断

5.2.8 srta.get_siteset函数​

获取媒体站点集ID。返回值参考[系统常量]

siteset = srta.get_siteset() -- 获取媒体站点集ID

-- 以下为返回值示例
21 -- 21代表微信，可以用srta常量进行判断

5.2.9 srta.get_expid函数​

获取实验分桶编号。返回值为 0-10。1-10 每个分桶 UV 比例接近于 10%。由于系统原因，目前线上极少量的流量不会被分到任何实验分组，当分桶号为 0 时，代表流量未分桶。

expid = srta.get_expid() -- 获取实验分桶号

-- 以下为返回值示例
5 -- 代表5号分桶

5.2.10 srta.get_geo_nearest函数​

获取地理位置最近的数据。传入搜索半径（单位：公里），返回距离（单位：米）和对应的数据表。

该函数用于查询用户常住地理位置附近的数据，例如查找附近门店、附近广告等场景。

distance, geoData = srta.get_geo_nearest(3) -- 查询3公里范围内最近的数据

-- 以下为返回值示例
distance = 1500 -- 距离为1500米
geoData = {
    [1] = {10, 20, 30, ...}, -- U8 字段区
    [2] = {100, 200, ...},   -- U32 字段区
    [3] = {true, false, ...} -- FLAG 字段区
}

参数说明：

  • 参数1：搜索半径，单位为公里（km），类型为整数

返回值说明：

  • 返回值1：距离，单位为米（m），类型为整数。如果未找到数据，返回最大uint32值 4294967295（0xFFFFFFFF）
  • 返回值2：数据表，结构与 srta.get_dsdata 返回的表结构相同。如果未找到数据，返回空表

使用场景：

  • 基于LBS的广告投放：根据用户常住位置推送附近商家广告
  • 地域性活动推广：向特定区域用户推送本地活动信息
  • 门店引流：向门店附近用户推送优惠信息

5.3 内置模块string​

string为字符串计算相关功能函数。

5.3.1 函数列表​

函数名功能
string.split切割字符串

5.3.2 string.split函数​

使用指定的分割符(sep)对字符串进行分割，并返回分割后的字符串数组。

str = "test,a,b"
strs = string.split(str, ",")
print("strs len" , #strs)
for i, item in ipairs(strs) do
    print(i, item)
end
-- 以下为字段返回示例
3
1   test
2   a
3   b

5.4 内置模块time​

time为时间计算相关功能函数，系统使用uint32为基础格式，存放Unix Timestamp。

5.4.1 函数列表​

函数名功能
time.now获取当前时间
time.date获取日期，一次返回年月日
time.hour获取小时
time.minute获取分钟
time.second获取秒
time.weekday获取星期几，星期日为 0，星期一为 1，以此类推
time.truncate向下取整，第二参数可指定取整类型
time.addtime增减时间，可一次增减时分秒
time.adddate增减日期，可一次增减年月日
time.setdate设置日期，可一次设置年月日时分秒

5.4.2 time.now函数​

函数获取当前时间戳，返回值为uint32类型。

now = time.now()

5.4.3 time.date函数​

函数传入时间戳，一次返回年、月、日三个值。

now = time.now()
year, month, day = time.date(now)

5.4.4 time.hour函数​

函数传入时间戳，返回小时。

now = time.now()
hour = time.hour(now)

5.4.5 time.minute函数​

函数传入时间戳，返回分钟。

now = time.now()
minute = time.minute(now)

5.4.6 time.second函数​

函数传入时间戳，返回秒。

now = time.now()
second = time.second(now)

5.4.7 time.weekday函数​

函数传入时间戳，返回星期几。星期天为 0，星期一为 1，以此类推。

now = time.now()
weekday = time.weekday(now)

5.4.8 time.truncate函数​

函数传入时间戳，及截断精度，返回截断后的时间戳。

时间精度可以是以下值：month、day、hour、minute。

now = time.now()
month_start = time.truncate(now, "month") -- 本月开始时间戳
today_start = time.truncate(now, "day") -- 今天开始时间戳
hour_start = time.truncate(now, "hour") -- 本小时开始时间戳
minute_start = time.truncate(now, "minute") -- 本分钟开始时间戳

5.4.9 time.addtime函数​

函数传入时间戳，及增减时间（时分秒），时分秒可为 0 或 负值，返回增减后的时间戳。

now = time.now()
newstamp = time.addtime(now, -1, 1, 1) -- 前1小时，再增加1分1秒

5.4.10 time.adddate函数​

函数传入时间戳，及增减日期（年月日），年月日可为 0 或 负值，返回增减后的时间戳。

now = time.now()
newstamp = time.adddate(now, -1, 1, 1) -- 去年，再增加1月1天

5.4.11 time.setdate函数​

函数传入年月日时分秒，返回时间戳。

newstamp = time.setdate(2025, 6, 18, 12, 13, 14) -- 2025:06:18 12:13:14

5.5 被调函数​

5.5.1 一次请求main​

5.5.1.1 调用​

业务逻辑由使用方实现，为便于系统调用，约定使用main函数名。该函数无入口参数，后续所需数据通过调用内置函数获取

function main()
    didData = srta.get_dsdata(srta.DS_DID) -- 获取DID数据
    local results = {} -- 返回结果
    
    -- 客户逻辑
    ...

    return results
end

较为完整的使用示例

-- 客户自定义变量，便于理解
IDXU8_NEWS = 1
IDXU8_MUSIC = 2
IDXU8_VIDEO = 3

IDXFLAG_NEWS = 1
IDXFLAG_MUSIC = 2

function main()
    didData = srta.get_dsdata(srta.DS_DID) -- 获取DID数据
    targets = srta.get_targets()
    local results = {} -- 返回结果
    
    for i, targetid in ipairs(targets) do -- 遍历待决策策略ID
        if targetid == "news" then -- 新闻拉活策略
            local is_news_installed = didData[srta.U8][IDXU8_NEWS] == 1 -- 是否新闻已安装
            local is_news_touched = didData[srta.FLAG][IDXFLAG_NEWS] -- 是否新闻已完成当天唤起
            if is_news_installed and (not is_news_touched) then
                results[targetid] = { [srta.TARGETINFO_ENABLE] = true } -- 已安装未拉活，可出拉活广告
            end
        end

        if targetid == "music" then -- 音乐拉活策略
            local is_music_installed = didData[srta.U8][IDXU8_MUSIC] == 1 -- 是否音乐已安装
            local is_music_touched = didData[srta.FLAG][IDXFLAG_MUSIC] -- 是否音乐已完成当天唤起
            if is_music_installed and (not is_music_touched) then
                results[targetid] = { [srta.TARGETINFO_ENABLE] = true } -- 已安装未拉活，可出拉活广告
            end
        end
    
        if targetid == "video_for_new" then -- 视频拉新策略
            local is_video_not_installed = didData[srta.U8][IDXU8_VIDEO] == 0 -- 是否视频未安装
            if is_video_not_installed then
                results[targetid] = { [srta.TARGETINFO_ENABLE] = true } -- 未安装，可出拉新广告
            end
        end
    end

    return results
end

5.5.1.2 返回​

主函数返回一个结果，为table格式并可引用srta常量以设置以下成员编号

成员类型功能
srta.TARGETINFO_ENABLEbool策略是否参竞
srta.TARGETINFO_CPC_PRICEint策略CPC出价
srta.TARGETINFO_CPA_PRICEint策略CPA出价
srta.TARGETINFO_USER_WEIGHT_FACTORfloat策略用户权重系数
srta.TARGETINFO_CPC_FACTORfloat策略CPC出价系数
srta.TARGETINFO_DC_INFOStable数组DCA标签信息（可选）

DCA标签信息格式

srta.TARGETINFO_DC_INFOS 为一个数组，其中每个元素为包含 DCA 标签的 table 结构：

results[targetid] = {
    [srta.TARGETINFO_ENABLE] = true,
    [srta.TARGETINFO_CPC_PRICE] = 100,
    [srta.TARGETINFO_DC_INFOS] = {
        {
            [srta.DC_TAG_NAME] = "tag_name_1",    -- DCA标签名称
            [srta.DC_TAG_VALUE] = "tag_value_1"   -- DCA标签值
        },
        {
            [srta.DC_TAG_NAME] = "tag_name_2",
            [srta.DC_TAG_VALUE] = "tag_value_2"
        }
    }
}

5.5.2 二次请求second​

5.5.2.1 调用​

待更新

5.5.2.2 返回​

待更新

5.6 代码调试​

sRTA 创建了完全独立的 LUA 运行时，有自己的生态库及机密数据依赖，所以无法在IDE内调试。需要通过 API接口 提交代码在服务端沙箱运行并返回结果。

根据数据源的不同，在沙箱运行有不同的限制。

引用数据源真实数据沙箱数据说明
一方可可可通过 API 参数传递 did/openid 信息，沙箱在运行 srta.get_dsdata 时自动读取存储于服务端的用户数据。
也可用hijack模拟
二方否可通过hijack模拟返回
三方否可通过hijack模拟返回

5.6.1 沙箱函数hijack​

5.6.1.1 入口​

约定使用hijack函数名并由使用方实现，在该函数内可以劫持部分系统模块功能调用，以桩数据内容返回。该函数无入口参数。

function hijack()
    local sandbox = {}
    -- 数据模拟

    return sandbox
end

5.6.1.2 返回​

hijack函数返回一个沙箱结果集合。

较为完整的使用示例

function hijack()
    print("hijack run")
    local sandbox = {
        srta_get_dsdata = {
            [srta.DS_DID] = {[srta.U8] = {[1] = 100},
                [srta.U32] = {[2] = 99},
                [srta.FLAG] = {[1] = true}
            }
        },
        srta_get_targets = {"t1", "t2", "t3"},
        srta_get_apps = {
            [13717681] = true,
            [3704767080] = true
        },
        srta_get_scores = {
            [200701123] = 10,
            [200701129] = 50
        },
        srta_get_os = srta.OS_IOS,
        srta_get_expid = 1,
        srta_get_siteset = srta.SITESET_WECHAT,
        srta_get_geo_nearest = {
            [1] = 1500, -- 距离(米)
            [2] = {
                [srta.U8] = {[1] = 10, [2] = 20},
                [srta.U32] = {[1] = 100},
                [srta.FLAG] = {[1] = true}
            }
        },
        time_now = 1755414905,
        geo_ip = 110000,       -- IP城市行政区划码（如110000代表北京市），用于srta.get_dsdata(srta.DS_GEOIP)
        geo_fac = 610100,      -- 常住城市行政区划码（如610100代表西安市），用于srta.get_dsdata(srta.DS_GEOFAC)
        geo_lnglat = {116.397128, 39.907507}  -- 经纬度{lng, lat}，用于srta.get_geo_nearest()
    }

    return sandbox
end

DCA标签信息沙箱模拟

在 hijack 函数中可以模拟返回 DCA 标签信息。DCA 标签作为策略返回值的一部分，用于设定广告的动态创意属性：

function hijack()
    local sandbox = {
        -- 其他模拟数据...
        -- main函数中返回的数据会通过DCA标签进行增强
    }
    return sandbox
end

function main()
    targets = srta.get_targets()
    local results = {}
    
    for i, targetid in ipairs(targets) do
        results[targetid] = {
            [srta.TARGETINFO_ENABLE] = true,
            [srta.TARGETINFO_CPC_PRICE] = 100,
            [srta.TARGETINFO_DC_INFOS] = {
                {
                    [srta.DC_TAG_NAME] = "category",
                    [srta.DC_TAG_VALUE] = "electronics"
                },
                {
                    [srta.DC_TAG_NAME] = "brand",
                    [srta.DC_TAG_VALUE] = "tech_brand"
                }
            }
        }
    end
    
    return results
end

返回约定：

  • 一级成员变量：使用 模块名_函数。例如 srta.get_dsdata 函数，在 table 中命名为 srta_get_dsdata
  • 无参数函数：使用对应 模块名_函数 成员的值。例如 srta.get_os()，在上述例子中将返回 srta.OS_IOS
  • 单参数函数：使用对应 模块名_函数 成员的 以函数参数为索引的 次级值。例如 srta_get_dsdata(srta.DS_DID)，在上述例子中将返回 srta_get_dsdata[srta.DS_DID]的 value。
  • 多参数多返回函数：使用对应 模块名_函数 成员的 以函数参数为索引的 次级值。例如 srta_get_scores(1,3)，在上述例子中将返回 {10,50}。

hijack未填字段默认行为：

函数说明
srta_get_dsdata未指定则使用srta.get_dsdata获取对应用户的真实一方数据。只有部分字段指定时，由指定字段覆盖原DS对应值
srta_get_targets使用srta.get_targets获取真实的策略列表
srta_get_apps返回nil
srta_get_scores返回nil
srta_get_os使用ScriptRun接口调用的 os 字段，如调用接口未指定则为 srta.OS_ANDROID
srta_get_expid0
srta_get_siteset0
srta_get_geo_nearest返回距离为4294967295（0xFFFFFFFF）和空表
time_now使用time.now获取真实的系统时间
geo_ip使用请求中的IP地址解析行政区划码。如未指定则为0，srta.get_dsdata(srta.DS_GEOIP) 将返回空表
geo_fac使用请求中的常住城市行政区划码。如未指定则为0，srta.get_dsdata(srta.DS_GEOFAC) 将返回空表
geo_lnglat使用请求中的用户常住经纬度。如未指定则 srta.get_geo_nearest() 查无结果