Definindo um ID de usuário e User Details hasheados

Envie seu ID de usuário interno para a Singular para permitir o rastreamento entre dispositivos e relatórios de dados no nível do usuário.

Requisitos de ID de usuário

Privacidade e práticas recomendadas

Siga estas diretrizes ao implementar o rastreamento de ID de usuário para garantir a conformidade com a privacidade e a medição adequada entre dispositivos.

• Sem PII: A ID de utilizador não deve expor informações de identificação pessoal (PII), tais como endereços de correio eletrónico, nomes de utilizador ou números de telefone. Use um valor com hash exclusivo para seus dados primários.
• Consistência entre plataformas: O valor da ID de utilizador deve ser o mesmo identificador interno que capta em todas as plataformas (Web/Mobile/PC/Console/Offline) para uma medição precisa entre dispositivos.
• Dados de primeira parte: A Singular inclui o ID de utilizador nas exportações ao nível do utilizador, ETL e postbacks do BI interno (se configurado). O ID de utilizador é um dado de primeira parte e não é partilhado com terceiros.
• Persistência: O ID de utilizador persiste até ser explicitamente desativado utilizando unsetCustomUserId() ou até a aplicação ser desinstalada. Fechar ou reiniciar a aplicação não apaga o ID de utilizador.

Descrição geral da implementação

Quando definir o ID de utilizador

Utilize Singular.setCustomUserId() para definir o identificador de utilizador e Singular.unsetCustomUserId() para o limpar durante o fim de sessão.

Se você já souber a ID de usuário quando o aplicativo for aberto, configure-a usando a propriedade customUserId antes de inicializar o SDK Singular. Isso garante que o Singular receba a ID de usuário da primeira sessão. No entanto, a ID de utilizador normalmente não está disponível até que o utilizador se registe ou inicie sessão, caso em que deve chamar setCustomUserId() após a conclusão do fluxo de registo ou autenticação.

Métodos do SDK

Definir ID de usuário personalizada

Envie sua ID de usuário interna para a Singular para rastreamento entre dispositivos e relatórios no nível do usuário.

import 'package:singular_flutter_sdk/singular.dart';

// Set the user ID after login or registration
Singular.setCustomUserId('user_123456');

Assinatura do método:

static void setCustomUserId(String customUserId)

Exemplo: Definir ID de usuário após o login

Chame setCustomUserId() imediatamente após o utilizador concluir com sucesso a autenticação para garantir que todos os eventos subsequentes são associados ao seu ID de utilizador.

import 'package:singular_flutter_sdk/singular.dart';

Future<void> handleUserLogin(String email, String password) async {
  try {
    // Your authentication logic
    final response = await authenticateUser(email, password);

    if (response.success) {
      // Set the user ID in Singular after successful login
      Singular.setCustomUserId(response.userId);

      print('User ID set: ${response.userId}');

      // Navigate to home screen
      navigateToHome();
    }
  } catch (error) {
    print('Login failed: $error');
  }
}

Anular a definição do ID de utilizador personalizado

Limpe o ID de utilizador quando um utilizador termina a sessão para garantir um acompanhamento preciso da sessão para dispositivos com vários utilizadores.

import 'package:singular_flutter_sdk/singular.dart';

// Unset the user ID on logout
Singular.unsetCustomUserId();

Assinatura do método:

static void unsetCustomUserId()

Exemplo: Anular a definição do ID de utilizador no fim da sessão

Chame unsetCustomUserId() durante o fluxo de logout para limpar o ID do usuário e evitar a atribuição incorreta de eventos subsequentes.

import 'package:singular_flutter_sdk/singular.dart';

Future<void> handleUserLogout() async {
  try {
    // Clear app data and user session
    await clearUserSession();

    // Unset the user ID in Singular
    Singular.unsetCustomUserId();

    print('User ID cleared');

    // Navigate to login screen
    navigateToLogin();
  } catch (error) {
    print('Logout failed: $error');
  }
}

Definir ID de utilizador durante a inicialização

Se a ID de usuário estiver disponível quando o aplicativo for iniciado (por exemplo, o usuário já estiver conectado), configure-a durante a inicialização do SDK usando a propriedade customUserId. Isto garante que a primeira sessão inclui a ID de utilizador.

import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:shared_preferences/shared_preferences.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    initializeSingular();
  }

  Future<void> initializeSingular() async {
    // Check if user is already logged in
    final prefs = await SharedPreferences.getInstance();
    final userId = prefs.getString('user_id');

    // Create configuration
    SingularConfig config = SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    // If user ID exists, set it during initialization
    if (userId != null) {
      config.customUserId = userId;
    }

    // Initialize SDK
    Singular.start(config);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(),
    );
  }
}

Propriedade de configuração:

String? customUserId

User Details hasheados (e-mail e telefone)

O ID de usuário acima é o seu próprio identificador opaco. Se você também quiser enviar o endereço de e-mail ou o número de telefone do usuário para a Singular, use a API separada SingularUserDetails. O SDK normaliza e aplica SHA-256 a esses valores no dispositivo, de modo que o e-mail e o telefone originais nunca são transmitidos.

Escolhendo um modo de hash

Há duas formas de fornecer os User Details. Escolha uma por usuário e mantenha a consistência.

• Hash pelo SDK (recomendado): Defina o e-mail ou o telefone em texto simples. O SDK normaliza o valor, aplica o hash e gera todas as variantes com as quais a Singular pode fazer correspondência.
• Pré-hasheado: Defina valores que você já normalizou e aplicou SHA-256. O SDK os armazena exatamente como foram fornecidos e não faz nenhum processamento adicional. Use esta opção quando o app não puder manter User Details em texto simples no momento da chamada.

Propriedades de SingularUserDetails

SingularUserDetails expõe seis propriedades String nullable. Atribua as que você tiver e deixe as demais sem definir.

Definindo os User Details na inicialização

Defina os User Details no seu SingularConfig antes de chamar Singular.start para que sejam anexados à primeira sessão enviada pelo SDK. Você pode atribuir diretamente a propriedade userDetails ou chamar withUserDetails; as duas formas são equivalentes.

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_user_details.dart';

SingularUserDetails userDetails = SingularUserDetails();
userDetails.email = 'user@example.com';
userDetails.phoneNumber = '+15551234567';

SingularConfig config = SingularConfig('SDK KEY', 'SDK SECRET');
config.withUserDetails(userDetails);

Singular.start(config);

Assinatura do método:

void withUserDetails(SingularUserDetails userDetails)

Definindo os User Details após a inicialização

Se o endereço de e-mail ou o número de telefone só for conhecido após o login ou o cadastro, chame Singular.setUserDetails nesse momento. A partir daí, os valores são anexados a todas as sessões e eventos enviados pelo SDK.

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_user_details.dart';

// Valores em texto simples, hasheados pelo SDK
SingularUserDetails userDetails = SingularUserDetails();
userDetails.email = 'user@example.com';
userDetails.phoneNumber = '+15551234567';
Singular.setUserDetails(userDetails);

// Ou forneça seus próprios hashes SHA-256
SingularUserDetails hashed = SingularUserDetails();
hashed.emailSTD = 'b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514';
hashed.phoneE164 = '8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4';
Singular.setUserDetails(hashed);

Assinatura do método:

static void setUserDetails(SingularUserDetails userDetails)

Apagando os User Details

Os User Details armazenados persistem no dispositivo entre as aberturas do app e são removidos quando o app é desinstalado. Chame Singular.clearUserDetails no logout, ou sempre que o usuário retirar o consentimento, para removê-los.

import 'package:singular_flutter_sdk/singular.dart';

// Remover os User Details armazenados no logout
Singular.clearUserDetails();

Assinatura do método:

static void clearUserDetails()

Validação e comportamento de privacidade

• Validação de e-mail: Um e-mail em texto simples deve conter exatamente um @ e um ponto depois dele. Valores inválidos são rejeitados e registrados, e não são enviados.
• Validação de telefone: Um número de telefone em texto simples deve conter pelo menos 6 dígitos. Valores mais curtos são rejeitados e registrados.
• Proteção contra modo incorreto: Um valor que já pareça hasheado é rejeitado por email e phoneNumber. Da mesma forma, as propriedades pré-hasheadas rejeitam qualquer valor que não seja uma string hexadecimal SHA-256 de 64 caracteres.
• Armazenamento: O payload hasheado é mantido no armazenamento privado do app em cada plataforma e é removido quando o app é desinstalado. Valores em texto simples nunca são armazenados.
• Limit Data Sharing: Enquanto o Limit Data Sharing estiver ativado, o payload de User Details é excluído de todas as requisições. Consulte Privacidade de dados.
• Consentimento: Colete e envie endereços de e-mail e números de telefone apenas quando houver base legal para isso. O hash não elimina as suas obrigações sob o GDPR, a CCPA ou regulamentações equivalentes.