Guía de recuperación de datos de dispositivos
Guía completa para recuperar los identificadores de dispositivos específicos de la plataforma y los parámetros necesarios para la atribución precisa de la API S2S y la medición de campañas.
Identificadores de dispositivo requeridos: Singular requiere identificadores de dispositivo específicos en todas las solicitudes de API para una atribución precisa.
Plataformas móviles:
- Android (Google Play): Google Advertising ID (GAID/AIFA) y App Set ID (ASID)
- Android (Amazon): Amazon Advertising ID (AMID) para dispositivos Fire
- Android (OEM chinos): Open Advertising ID (OAID) para dispositivos sin Google Play Services
- Android (Fallback): Android ID (ANDI) sólo cuando no hay otros identificadores disponibles
- iOS: Identificador para vendedores (IDFV) e Identificador para anunciantes (IDFA) cuando estén disponibles
Parámetros del dispositivo: Localidad, marca del dispositivo, modelo del dispositivo y versión de compilación necesarios para las plataformas móviles
Los siguientes ejemplos de código muestran métodos de recuperación para cada plataforma y tipo de identificador.
Ejemplos de aplicaciones
Implementaciones de referencia
Ejemplos de trabajo completos para iOS y Android que demuestran patrones de recuperación de datos de dispositivos.
Identificadores de dispositivos iOS
Los dispositivos iOS requieren IDFV (siempre) e IDFA (cuando el usuario concede permiso de seguimiento) más el estado de autorización ATT para una atribución precisa.
Identificadores de iOS requeridos
Requisitosdel identificador:
- IDFV: Se requiere en todas las solicitudes S2S independientemente del permiso de seguimiento.
- IDFA: debe proporcionarse si el usuario concede el consentimiento de App Tracking Transparency
- Estado ATT: Código de estado de autorización requerido en todas las solicitudes (0-3)
Guía de implementación
Identificador para anunciantes (IDFA)
El Identificador para Anunciantes (IDFA) permite a los anunciantes rastrear y atribuir las acciones de los usuarios (clics en anuncios, instalaciones de aplicaciones) a campañas específicas para una orientación y optimización precisas.
A partir de iOS 14.5, los usuarios deben dar su consentimiento a través del marco App Tracking Transparency (ATT) antes de que las apps accedan al IDFA. Sin el consentimiento del usuario, IDFA devuelve todos los ceros, limitando las capacidades de seguimiento.
Identificador para proveedores (IDFV)
El identificador para proveedores (IDFV) es un identificador único asignado por Apple al dispositivo, específico del proveedor/desarrollador. Permanece consistente en todas las aplicaciones del mismo proveedor en el dispositivo, permitiendo el seguimiento del comportamiento entre aplicaciones sin identificación personal.
Medidas de aplicación:
- Asegúrese de que se muestra y gestiona el aviso ATT antes de intentar acceder al IDFA.
- Capturar el IDFA (si está autorizado) y pasarlo al servidor para solicitudes API.
- Capturar IDFV y pasarlo al servidor para solicitudes API (siempre obligatorio)
- Incluir el estado de autorización ATT en todas las solicitudes
Ejemplos de código
Solicitud de autorización ATT y recuperación de IDFA/IDFV
#import <AdSupport/AdSupport.h>
#import <AppTrackingTransparency/AppTrackingTransparency.h>
#import <UIKit/UIKit.h>
- (void)retrieveIdentifiers {
// Request ATT authorization (iOS 14.5+)
[ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
dispatch_async(dispatch_get_main_queue(), ^{
switch (status) {
case ATTrackingManagerAuthorizationStatusAuthorized: {
// ATT authorized, retrieve IDFA
NSUUID *idfa = [[ASIdentifierManager sharedManager] advertisingIdentifier];
NSLog(@"IDFA: %@", [idfa UUIDString]);
NSLog(@"ATT Status: %ld", (long)status); // Status = 3
break;
}
case ATTrackingManagerAuthorizationStatusDenied:
NSLog(@"ATT Status: Denied (%ld)", (long)status); // Status = 2
break;
case ATTrackingManagerAuthorizationStatusRestricted:
NSLog(@"ATT Status: Restricted (%ld)", (long)status); // Status = 1
break;
case ATTrackingManagerAuthorizationStatusNotDetermined:
NSLog(@"ATT Status: Not Determined (%ld)", (long)status); // Status = 0
break;
default:
NSLog(@"Unknown ATT status.");
break;
}
// Retrieve IDFV (always available)
NSUUID *idfv = [[UIDevice currentDevice] identifierForVendor];
if (idfv != nil) {
NSLog(@"IDFV: %@", [idfv UUIDString]);
} else {
NSLog(@"Unable to retrieve IDFV.");
}
});
}];
}
// Call the method to retrieve identifiers
[self retrieveIdentifiers];import AdSupport
import AppTrackingTransparency
import UIKit
func retrieveIdentifiers() {
// Request ATT authorization (iOS 14.5+)
ATTrackingManager.requestTrackingAuthorization { status in
DispatchQueue.main.async {
switch status {
case .authorized:
// ATT authorized, retrieve IDFA
let idfa = ASIdentifierManager.shared().advertisingIdentifier.uuidString
print("IDFA: \(idfa)")
print("ATT Status: \(status.rawValue)") // Status = 3
case .denied:
print("ATT Status: Denied (\(status.rawValue))") // Status = 2
case .restricted:
print("ATT Status: Restricted (\(status.rawValue))") // Status = 1
case .notDetermined:
print("ATT Status: Not Determined (\(status.rawValue))") // Status = 0
@unknown default:
print("Unknown ATT status.")
}
// Retrieve IDFV (always available)
if let idfv = UIDevice.current.identifierForVendor?.uuidString {
print("IDFV: \(idfv)")
} else {
print("Unable to retrieve IDFV.")
}
}
}
}
// Call the function to retrieve identifiers
retrieveIdentifiers()Disponibilidad del identificador:
- IDFA: Requiere autorización ATT desde iOS 14.5+. Sin autorización, devuelve todos ceros
- IDFV: Siempre disponible-incluir en todas las solicitudes de API Singular
- Valores de estado ATT: 0=Indeterminado, 1=Restringido, 2=Rechazado, 3=Autorizado
Identificadores de dispositivos Android (Google Play)
Los dispositivos Android con Google Play Services requieren App Set ID (ASID) en todas las solicitudes, con Google Advertising ID (GAID/AIFA) cuando esté disponible.
Identificadores de Google Play requeridos
Requisitos delos identificadores:
- ASID: requerido en todas las solicitudes S2S para dispositivos Google Play
- AIFA/GAID: Deben proporcionarse cuando estén disponibles (sin exclusión)
Guía de implementación
Identificador de publicidad de Google (GAID)
El identificador de publicidad de Google (GAID), también conocido como AIFA o ID de publicidad de Android (AAID), es un identificador único que el usuario puede restablecer y que se asigna a los dispositivos Android. Permite a los anunciantes y a los desarrolladores rastrear y atribuir las acciones de los usuarios en las aplicaciones para la orientación y la optimización de las campañas, al tiempo que se mantiene la privacidad.
Dependencias
Añada la dependencia necesaria en su sitio build.gradle:
dependencies {
implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
}Permisos
Si se dirige a Android 12/API nivel 31+, añada el permiso en AndroidManifest.xml:
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />Uso
AdIdUtils.getGoogleAdId(getApplicationContext());Implementación
import android.content.Context;
import android.os.AsyncTask;
import android.util.Log;
import com.google.android.gms.ads.identifier.AdvertisingIdClient;
import com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
public class AdIdUtils {
public static void getGoogleAdId(Context context) {
AsyncTask.execute(new Runnable() {
@Override
public void run() {
try {
Info adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context);
String adId = adInfo.getId();
boolean isLimitAdTrackingEnabled = adInfo.isLimitAdTrackingEnabled();
Log.d("GoogleAdID", "Advertising ID: " + adId);
Log.d("GoogleAdID", "Limit Ad Tracking: " + isLimitAdTrackingEnabled);
} catch (Exception e) {
Log.e("GoogleAdID", "Error retrieving GAID", e);
}
}
});
}
}Dependencias
dependencies {
implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
}Permisos
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />Uso
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.launch
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
lifecycleScope.launch {
val googleAdId = AdIdUtils.getGoogleAdId(applicationContext)
Log.d("MainActivity", "Retrieved Google Ad ID: $googleAdId")
}
}
}Implementación
import android.content.Context
import android.util.Log
import com.google.android.gms.ads.identifier.AdvertisingIdClient
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
object AdIdUtils {
suspend fun getGoogleAdId(context: Context): String? {
return withContext(Dispatchers.IO) {
try {
val adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
val adId = adInfo.id
val isLimitAdTrackingEnabled = adInfo.isLimitAdTrackingEnabled
Log.d("GoogleAdID", "Advertising ID: $adId")
Log.d("GoogleAdID", "Limit Ad Tracking: $isLimitAdTrackingEnabled")
adId
} catch (e: Exception) {
Log.e("GoogleAdID", "Error retrieving GAID", e)
null
}
}
}
}App Set ID (ASID)
Android App Set ID proporciona un seguimiento de aplicaciones cruzadas que respeta la privacidad para el mismo desarrollador. Resulta útil para el análisis y la prevención del fraude, pero no puede utilizarse para publicidad personalizada.
Dependencias
dependencies {
implementation 'com.google.android.gms:play-services-appset:16.1.0'
}Uso
AppSetIdUtils.getAppSetId(getApplicationContext());Implementación
import android.content.Context;
import android.util.Log;
import com.google.android.gms.appset.AppSet;
import com.google.android.gms.appset.AppSetIdClient;
import com.google.android.gms.appset.AppSetIdInfo;
import com.google.android.gms.tasks.Task;
public class AppSetIdUtils {
public static void getAppSetId(Context context) {
AppSetIdClient client = AppSet.getClient(context);
Task task = client.getAppSetIdInfo();
task.addOnSuccessListener(info - {
String appSetId = info.getId();
int scope = info.getScope();
Log.d("AppSetID", "App Set ID: " + appSetId);
Log.d("AppSetID", "Scope: " + (scope == AppSetIdInfo.SCOPE_DEVELOPER ? "Developer" : "App"));
}).addOnFailureListener(e - {
Log.e("AppSetID", "Failed to retrieve App Set ID", e);
});
}
} Dependencias
dependencies {
implementation 'com.google.android.gms:play-services-appset:16.1.0'
}Uso
AppSetIdUtils.getAppSetId(applicationContext)Implementación
import android.content.Context
import android.util.Log
import com.google.android.gms.appset.AppSet
import com.google.android.gms.appset.AppSetIdClient
import com.google.android.gms.appset.AppSetIdInfo
object AppSetIdUtils {
fun getAppSetId(context: Context) {
val client: AppSetIdClient = AppSet.getClient(context)
val task = client.appSetIdInfo
task.addOnSuccessListener { info -
val appSetId: String = info.id
val scope: Int = info.scope
Log.d("AppSetID", "App Set ID: $appSetId")
Log.d("AppSetID", "Scope: ${if (scope == AppSetIdInfo.SCOPE_DEVELOPER) "Developer" else "App"}")
}.addOnFailureListener { exception -
Log.e("AppSetID", "Failed to retrieve App Set ID", exception)
}
}
}Identificadores de dispositivos Android (sin Google Play)
Los dispositivos Android sin Google Play Services requieren identificadores alternativos basados en el fabricante del dispositivo y el método de distribución.
Identificador de dispositivo Amazon
AMID: El identificador de publicidad de Amazon debe proporcionarse para los dispositivos Amazon Fire sin servicios de Google Play.
Identificador de Amazon (AMID)
El Identificador de Publicidad de Amazonpermite el seguimiento de publicidad reseteable por el usuario en dispositivos Amazon Fire sin Google Play Services, manteniendo la privacidad del usuario a la vez que permite la atribución.
Requisitos:
- Funciona en dispositivos Amazon Fire con Fire OS 5.1+.
- Respeta la preferencia del usuario de limitar el seguimiento de anuncios.
- Puede no estar disponible en dispositivos que no sean Fire OS
Uso
AdvertisingIdHelper.getAmazonAdvertisingId(getContentResolver());Implementación
import android.content.ContentResolver;
import android.provider.Settings;
import android.provider.Settings.SettingNotFoundException;
import android.util.Log;
public class AdvertisingIdHelper {
public static void getAmazonAdvertisingId(ContentResolver contentResolver) {
String advertisingID = "";
boolean limitAdTracking = false;
try {
limitAdTracking = Settings.Secure.getInt(contentResolver, "limit_ad_tracking") != 0;
advertisingID = Settings.Secure.getString(contentResolver, "advertising_id");
Log.d("AdvertisingID", "Amazon Advertising ID: " + advertisingID);
Log.d("LimitAdTracking", "Limit Ad Tracking: " + limitAdTracking);
} catch (SettingNotFoundException e) {
Log.e("AdvertisingID", "Advertising ID not supported on this device", e);
}
}
}Uso
AdvertisingIdHelper.getAmazonAdvertisingId(contentResolver)Implementación
import android.content.ContentResolver
import android.provider.Settings
import android.util.Log
object AdvertisingIdHelper {
fun getAmazonAdvertisingId(contentResolver: ContentResolver) {
try {
val limitAdTracking = Settings.Secure.getInt(contentResolver, "limit_ad_tracking") != 0
val advertisingID = Settings.Secure.getString(contentResolver, "advertising_id")
Log.d("AdvertisingID", "Amazon Advertising ID: $advertisingID")
Log.d("LimitAdTracking", "Limit Ad Tracking: $limitAdTracking")
} catch (e: Settings.SettingNotFoundException) {
Log.e("AdvertisingID", "Advertising ID not supported on this device", e)
}
}
}Identificador OEM chino
OAID: El identificador de publicidad abierto debe proporcionarse para los dispositivos fabricados en China sin Google Play Services.
Identificador de publicidad abierta (OAID)
Open Advertising Identifier (OAID) es un identificador único y anónimo para publicidad en dispositivos Android fabricados en China. Introducido por Mobile Security Alliance (MSA) como alternativa a GAID para dispositivos en los que Google Play Services no está disponible.
Dispositivos compatibles: Huawei, Xiaomi, OPPO, Vivo y otros dispositivos Android fabricados en China.
Acceso a través de MSA SDKo Huawei Mobile Services (HMS).
Dependencias
dependencies {
implementation 'com.bun.msa.sdk:msa:1.0.26'
}Implementación
import android.os.Bundle;
import android.util.Log;
import androidx.appcompat.app.AppCompatActivity;
import com.bun.msa.sdk.DeviceId;
import com.bun.msa.sdk.DeviceIdSupplier;
import com.bun.msa.sdk.IIdentifierListener;
public class MainActivity extends AppCompatActivity {
private static final String TAG = "OAIDExample";
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
getOAID();
}
private void getOAID() {
try {
DeviceId deviceId = new DeviceId(this);
deviceId.getDeviceIds(new IIdentifierListener() {
@Override
public void onSupport(boolean isSupport, DeviceIdSupplier supplier) {
if (isSupport && supplier != null) {
String oaid = supplier.getOAID();
Log.d(TAG, "OAID: " + oaid);
} else {
Log.e(TAG, "OAID not supported on this device");
}
}
});
} catch (Exception e) {
Log.e(TAG, "Error retrieving OAID", e);
}
}
}Dependencias
dependencies {
implementation 'com.bun.msa.sdk:msa:1.0.26'
}Implementación
import android.os.Bundle
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import com.bun.msa.sdk.DeviceId
import com.bun.msa.sdk.DeviceIdSupplier
import com.bun.msa.sdk.IIdentifierListener
class MainActivity : AppCompatActivity() {
companion object {
private const val TAG = "OAIDExample"
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
getOAID()
}
private fun getOAID() {
try {
val deviceId = DeviceId(this)
deviceId.getDeviceIds(object : IIdentifierListener {
override fun onSupport(isSupport: Boolean, supplier: DeviceIdSupplier?) {
if (isSupport && supplier != null) {
val oaid = supplier.oAID
Log.d(TAG, "OAID: $oaid")
} else {
Log.e(TAG, "OAID not supported on this device")
}
}
})
} catch (e: Exception) {
Log.e(TAG, "Error retrieving OAID", e)
}
}
}Android ID Fallback
Restricciones de ANDI: Sólo se puede proporcionar el Android ID si no hay otros identificadores disponibles Y la aplicación no se distribuye a través de Google Play Store. Prohibido para aplicaciones de Google Play.
ID de Android (ANDI)
El Android ID es un identificador único de 64 bits que se genera al configurar el dispositivo por primera vez. A partir de Android 8.0 (Oreo), se asigna por aplicación y por usuario: las distintas aplicaciones reciben Android ID diferentes a menos que compartan la misma clave de firma.
Persistencia: Permanece constante a menos que el dispositivo se restablezca de fábrica o se desinstale/reinstale la aplicación tras una actualización OTA.
import android.provider.Settings;
import android.content.Context;
String androidId = Settings.Secure.getString(
context.getContentResolver(),
Settings.Secure.ANDROID_ID
);import android.provider.Settings
val androidId: String = Settings.Secure.getString(
contentResolver,
Settings.Secure.ANDROID_ID
)Identificadores web y multiplataforma
Las aplicaciones web y las implementaciones multiplataforma requieren un identificador de dispositivo singular (SDID) para un seguimiento preciso de la atribución.
Identificador Web requerido
SDID: Identificador de dispositivo singular requerido en todas las solicitudes S2S para plataformas Web, PC, Consola y CTV.
ID de dispositivo Singular Web SDK
Singular Device ID (SDID) proporciona un seguimiento coherente entre sesiones para aplicaciones web y plataformas no móviles.
Requisitos previos: Singular Web SDK debe estar implementado e inicializado antes de recuperar el SDID.
Uso
// Retrieve SDID after Singular SDK initialization
const sdid = window.singularSdk.getSingularDeviceId();
console.log("Singular Device ID:", sdid);
Nota de implementación: Llame a getSingularDeviceId()sólo después de que Singular SDK se haya inicializado correctamente; si intenta recuperarlo antes de la inicialización, el resultado será nulo.
Parámetros del dispositivo móvil
Los parámetros de dispositivo necesarios proporcionan un contexto esencial para la atribución y el análisis en plataformas móviles.
Parámetros obligatorios
Plataformas móviles: Localidad, marca de dispositivo, modelo de dispositivo y compilación requeridos en todas las solicitudes S2S para iOS y Android.
Recuperación de parámetros
Recopile información sobre la configuración regional, el fabricante, el modelo y la compilación para obtener un perfil completo del dispositivo.
#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>
#import <sys/sysctl.h>
// Retrieve Locale
NSString *retrieveLocale() {
NSString *locale = [[NSLocale currentLocale] localeIdentifier];
NSLog(@"Locale: %@", locale);
return locale;
}
// Retrieve Manufacturer (always Apple for iOS)
NSString *retrieveManufacturer() {
return @"Apple";
}
// Retrieve Device Model
NSString *deviceModel() {
size_t bufferSize = 64;
char model[bufferSize];
int status = sysctlbyname("hw.machine", model, &bufferSize, NULL, 0);
if (status == 0) {
NSString *deviceModel = [NSString stringWithCString:model encoding:NSUTF8StringEncoding];
NSLog(@"Device Model: %@", deviceModel);
return deviceModel;
} else {
NSLog(@"Unable to retrieve device model.");
return nil;
}
}
// Retrieve Build Version
NSString *buildVersion() {
size_t bufferSize = 64;
char build[bufferSize];
int status = sysctlbyname("kern.osversion", build, &bufferSize, NULL, 0);
if (status == 0) {
NSString *buildVersion = [NSString stringWithCString:build encoding:NSUTF8StringEncoding];
NSLog(@"Build Version: %@", buildVersion);
return buildVersion;
} else {
NSLog(@"Unable to retrieve build version.");
return nil;
}
}import Foundation
import UIKit
// Retrieve Locale
func retrieveLocale() - String {
let locale = Locale.current.identifier
print("Locale: \(locale)")
return locale
}
// Retrieve Manufacturer (always Apple for iOS)
func retrieveManufacturer() - String {
return "Apple"
}
// Retrieve Device Model
func deviceModel() - String? {
var systemInfo = utsname()
uname(&systemInfo)
let machineMirror = Mirror(reflecting: systemInfo.machine)
let identifier = machineMirror.children.reduce("") { identifier, element in
guard let value = element.value as? Int8, value != 0 else { return identifier }
return identifier + String(UnicodeScalar(UInt8(value)))
}
print("Device Model: \(identifier)")
return identifier
}
// Retrieve Build Version
func buildVersion() - String? {
var size: Int = 0
sysctlbyname("kern.osversion", nil, &size, nil, 0)
var build = [CChar](repeating: 0, count: size)
sysctlbyname("kern.osversion", &build, &size, nil, 0)
let buildVersion = String(cString: build)
print("Build Version: \(buildVersion)")
return buildVersion
}import android.os.Build;
import java.util.Locale;
// Locale (lc parameter)
String locale = Locale.getDefault().toString();
// Device Make (ma parameter)
String deviceMake = Build.MANUFACTURER;
// Device Model (mo parameter)
String deviceModel = Build.MODEL;
// Build (bd parameter)
String build = "Build/" + Build.ID;import android.os.Build
import java.util.Locale
// Locale (lc parameter)
val locale: String = Locale.getDefault().toString()
// Device Make (ma parameter)
val deviceMake: String = Build.MANUFACTURER
// Device Model (mo parameter)
val deviceModel: String = Build.MODEL
// Build (bd parameter)
val build: String = "Build/" + Build.IDAsignación de parámetros:
- Configuración regional (lc): Código de idioma y región (por ejemplo, en_US, zh_CN)
- Marca (ma): Fabricante del dispositivo (Apple, Samsung, Xiaomi)
- Modelo (mo): Modelo específico del dispositivo (iPhone14,2, SM-G991B)
- Versión (bd): Versión del sistema operativo prefijada con "Build/".