> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audiencia

> Enumera, obtén, crea y actualiza las audiencias de un vendedor de Partner Center.

Una audiencia es un grupo con nombre de jugadores o dispositivos, como evaluadores, al que un vendedor puede dirigir
contenido. Partner Center los llama grupos de clientes. Los comandos `audience` enumeran y obtienen las
audiencias de un vendedor, crean audiencias de usuarios conocidos, y cambian el nombre de una o reemplazan sus miembros. Para permitir que una
audiencia se una a un playtest, pasa su `id` a `playtest create` o `playtest update`; consulta
[Elección de audiencias](https://docs.xbox.com/es/tools/xbox-cli/commands/playtest.md#choosing-audiences).

`audience` es experimental: sus comandos, opciones y salida pueden cambiar o quitarse. Consulta
[Comandos experimentales](https://docs.xbox.com/es/tools/xbox-cli/cli-command-lifecycle.md). Enumerar y obtener audiencias requiere el permiso
de lectura de grupos de clientes de Partner Center para el vendedor, y crearlas y actualizarlas requiere el permiso
de escritura.

## Comandos

| Comando | Descripción |
| - | - |
| `audience list` | Enumera las audiencias del vendedor. |
| `audience get <audience-id>` | Obtiene una audiencia, con sus miembros. |
| `audience create` | Crea una audiencia de usuarios conocidos. |
| `audience update <audience-id>` | Cambia el nombre de una audiencia de usuarios conocidos o reemplaza su lista completa de miembros. |

La CLI no puede eliminar una audiencia ni cambiar su tipo; hazlo en Partner Center.

## Argumentos y opciones

| Argumento u opción | Se aplica a | Obligatorio | Descripción |
| - | - | - | - |
| `<audience-id>` | `get`, `update` | Sí | Identificador de la audiencia, exactamente como lo devuelve `list`, como `1152921504606846976`. |
| `--name <text>` | `list` | No | Enumera solo las audiencias cuyo nombre contiene este texto, sin distinguir mayúsculas de minúsculas. |
| `--name <text>` | `create`, `update` | `create` | Nombre de la audiencia, de hasta 200 caracteres. No puede estar en blanco y no tiene que ser único. |
| `--members-file <path>` | `create`, `update` | No | Archivo que enumera los miembros. Consulta [Archivos de miembros](#members-files). |
| `--confirm` (`--yes`, `-y`) | `create`, `update` | No | Omite la solicitud de confirmación. Sin esta opción, el comando pregunta en un terminal y, en caso contrario, falla. |
| `--seller-id <id>` | todos | Si no está guardado | Identificador de vendedor de Partner Center. Consulta [Contexto](https://docs.xbox.com/es/tools/xbox-cli/commands/context.md). |
| `--base-url <url>` | todos | No | URL base de las solicitudes, que invalida la clave de configuración `XboxPartner:BaseUrl`. |
| `--output <format>` | todos | No | `json` (predeterminado), `json-compact` o `table`. |

## Salida

`audience get` escribe una audiencia:

```json theme={null}
{
  "name": "Nod Arena testers",
  "id": "1152921504606846976",
  "members": ["dev@nodpublishers.com"],
  "dnaTags": ["AppFlighting"],
  "sellerId": "1234567",
  "groupType": "User",
  "groupUsage": "ForPackageFlight, ForLimitedDistribution"
}
```

| Campo | Descripción |
| - | - |
| `name` | El nombre de la audiencia, o `null`. |
| `id` | El identificador de la audiencia. Pásalo sin cambios a otros comandos. |
| `members` | Los miembros almacenados. `list` omite este campo. |
| `dnaTags` | Las etiquetas de la audiencia. |
| `sellerId` | El vendedor propietario de la audiencia. |
| `groupType` | El tipo de audiencia, como `User`, `PreCreated` o `XboxDevice`, o `null`. Solo se pueden actualizar las audiencias `User`. |
| `groupUsage` | Para qué se usa la audiencia, como marcas separadas por comas, o `null`. |

`audience list` escribe una matriz `audiences` de los mismos objetos, sin `members`, y
`{"audiences":[]}` cuando no hay ninguna. `create` y `update` escriben la audiencia igual que `get`.

Con `--output table`, todos los comandos muestran las columnas `ID`, `NAME` y `TYPE`, donde `TYPE` es
`groupType`. Los miembros solo aparecen en la salida JSON.

## Creación de una audiencia

```bash theme={null}
xbox audience create --name "Nod Arena testers" --members-file testers.txt
```

Sin `--members-file`, la audiencia no tiene miembros. Cada ejecución crea una audiencia nueva, aunque
ya exista una con el mismo nombre.

## Actualización de una audiencia

Pasa `--name`, `--members-file` o ambas; lo que omitas se conserva. Esto cambia el nombre de una audiencia:

```bash theme={null}
xbox audience update 1152921504606846976 --name "Nod Arena beta testers"
```

Esto reemplaza sus miembros por las direcciones de `testers.txt`:

```bash theme={null}
xbox audience update 1152921504606846976 --members-file testers.txt
```

> [!WARNING]
>
> `--members-file` reemplaza la lista completa de miembros. Los miembros que no están en el archivo se quitan, y un
> archivo vacío quita a todos los miembros. Para agregar o quitar un miembro, lee la lista con `audience get`,
> cámbiala y pasa la lista completa.

La actualización no se comprueba frente a otros cambios: si dos personas actualizan una audiencia a la vez,
prevalece la última.

## Archivos de miembros

Un archivo de miembros es texto UTF-8 con una dirección de correo electrónico por línea, hasta 1000 miembros:

```text theme={null}
dev@nodpublishers.com
tester@nodpublishers.com
```

Se omiten las líneas en blanco y los espacios alrededor de cada línea. El servicio comprueba cada miembro, pero un miembro
almacenado no demuestra que corresponda a una cuenta que pueda ver el contenido dirigido a la audiencia.

## Códigos de salida

| Código de salida | Significado |
| - | - |
| `0` | El comando se completó correctamente. |
| `1` | El comando falló y no cambió nada. |
| `3` | `create` o `update` envió su solicitud, pero se desconoce su resultado. El identificador de correlación está en stderr. |

`create` y `update` envían su solicitud una sola vez. Después de la salida `3`, comprueba antes de volver a ejecutar
el comando:

* Después de `create`, ejecuta el comando `xbox audience list --name` que muestra stderr. Una coincidencia es solo un
  indicio, porque los nombres no tienen que ser únicos, y volver a ejecutar `create` puede crear una segunda
  audiencia.
* Después de `update`, ejecuta `xbox audience get <audience-id>` para comprobar su nombre y sus miembros.

## Errores

Los errores van a stderr como texto, sea cual sea `--output`, con el identificador de correlación, indicaciones para el
estado HTTP y el detalle del error del servicio, cuando lo hay. `--verbose` agrega la respuesta del servicio,
que puede incluir miembros. Los scripts deben bifurcarse según el código de salida, no según el texto.

Un 403 puede indicar que falta un permiso, que no perteneces al vendedor o que los playtests
no están habilitados para él. En `list` y `get`, un rechazo puede aparecer en su lugar como un 502; consulta el detalle
del error para conocer la causa. La creación y actualización de audiencias se está implementando gradualmente y es posible que aún no esté disponible
para ti; hasta que lo esté, `create` y `update` fallan sin cambiar nada.

## Ejemplos

Enumerar y obtener audiencias:

```bash theme={null}
xbox audience list --name testers
xbox audience list --output table
xbox audience get 1152921504606846976 --seller-id 1234567
```

Crear una audiencia sin la solicitud de confirmación:

```bash theme={null}
xbox audience create --name "Nod Arena testers" --members-file testers.txt --confirm
```

Reemplazar los miembros de una audiencia y mostrar el resultado como una tabla:

```bash theme={null}
xbox audience update 1152921504606846976 --members-file testers.txt --output table
```


## Related topics

- [Visibilidad: audiencias](https://docs.xbox.com/es/publishing/game-publishing/concepts/availability/visibility-audiences.md)
- [Visibilidad](https://docs.xbox.com/es/publishing/game-publishing/concepts/availability/visibility.md)
- [Notificaciones de los tokens de seguridad de XBOX services](https://docs.xbox.com/es/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/security-tokens/live-token-claims.md)
- [Configurar precios y disponibilidad para un juego](https://docs.xbox.com/es/publishing/game-publishing/tutorial-xbox-managed/how-to-configure-pricing-and-availability.md)
- [Distribución de versiones piloto del XBOX Insider Program](https://docs.xbox.com/es/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-xbox-insider-flighting.md)
