1. Linguagem
1.1. Sintaxe
Como o AMPscript é um idioma do lado do servidor, o código pode ser incluído em qualquer local em um email, página da web, SMS ou mensagem push. Semelhante a outras linguagens de script, o AMPscript é interpretado e não compilado, o que significa que é interpretado na ordem em que é escrito. Portanto, se você estiver usando o AMPscript para incluir conteúdo personalizado em um email, o código AMPscript precisará ser definido antes ou no ponto em que o conteúdo personalizado deve aparecer.
1.2. Em bloco de AMPscript
O código AMPScript está contido em uma sequência de caracteres que abre e fecha com duas marcas percentuais %% e contém um delimitador de suporte interno [ e ]
%%[
/* Bloco de AMPScript */
var @nome, @idade
set @nome = "Maria"
set @idade = 30
if @idade >= 18 then
outputline("Olá ", @nome, "! Você é maior de idade.")
else
outputline("Olá ", @nome, "! Você é menor de idade.")
endif
]%%
Os blocos AMPscript são usados para definir o código para interpretação, mas não exibem a saída onde o código aparece no email ou na página. Existem algumas exceções a esta regra através do fornecimento de duas funções Saída e OutputLine, que habilitam variável valores a serem emitidos no local em que o bloco de código aparece.
1.3. Em linha de AMPscript
O código AMPScript está contido em uma sequência de caracteres que abre e fecha com duas marcar percentuais %% e contém um delimitador de suporte interno = e =
Olá %%=v(@nome)=%%, hoje é %%=Now()=%%.
O AMPscript embutido fornece um método conveniente de interpretar e executar uma função no conteúdo da mensagem. Diferentemente dos blocos AMPscript, o AMPscript em linha só pode ser usado com uma única função e a saída da função é exibida onde o código AMPscript em linha aparece. No entanto, funções aninhadas são suportadas.
1.4. Sintaxe baseada em tags
Como alternativa à sintaxe do bloco AMPscript, a tag do script HTML também é suportada. Essa sintaxe pode ser benéfica ao desenvolver em SSJS (Server-Side JavaScript) e AMPscript, pois fornece uma sintaxe padronizada para interpretar os dois idiomas de script do lado do servidor.
Os atributos de runat e language adicionais devem ser incluídos na tag de script de abertura para que o código que contém seja interpretado como AMPscript, conforme indicado no exemplo abaixo:
<script runat="server" language="ampscript">/* Código AMPscript */</script>
1.5. Funções
Na programação, a função é uma seção nomeada de um programa que usa alguns valores de entrada (ou argumentos) para executar uma tarefa específica e produzir um valor de saída. Enquanto outras linguagens de script oferecem funções definidas pelo usuário (por exemplo, JavaScript), o AMPscript usa uma abordagem declarativa por meio de funções predefinidas, orientadas principalmente para exibir, transformar e armazenar dados e conteúdo de marketing do clientes.
As funções do AMPscript funcionam da mesma maneira que no Microsoft Excel; isto é, os parâmetros são definidos para uma função predefinida, que é interpretada e, por sua vez, retorna um valor. Várias funções do AMPscript são idênticas às funções do Excel - enquanto algumas funções são nomeadas de maneira diferente, elas compartilham os mesmos parâmetros e produzem o mesmo resultado que o Excel.
1.5.1. AMPScript e Excel
Há um total de 15 funções comparáveis entre Excel e AMPscript que aceitam os mesmos parâmetros e emitem o mesmo resultado, conforme indicado na tabela abaixo.
1.6. Variáveis
Semelhante a outras linguagens de programação e script, o AMPscript oferece suporte a variáveis . Na programação, as variáveis fornecem um método conveniente de definir uma função ou valor uma vez e, em seguida, reutilizar essa variável referenciando-a no código. Isso é da mesma forma que as classes Cascading Style Sheets (CSS) são definidas uma vez e, em seguida, as propriedades de estilo definidas são aplicadas a um ou mais elementos, incluindo o nome da classe em um atributo de classe. No entanto, as variáveis não apenas permitem que valores fixos (ou ) sejam definidos uma vez, mas também funções AMPscript e, por sua vez, o valor de saída da variável pode mudar dependendo do contexto para o qual é interpretado. 1.6.1. Convenção de nomes
As variáveis são essencialmente 'contêineres nomeados', onde um nome definido pelo usuário é aplicado a uma entidade definida, seja uma constante ou função. Os nomes de variáveis não diferenciam maiúsculas de minúsculas e podem incluir caracteres ou números, mas não espaços ou vírgulas. Os nomes das variáveis devem começar @ e incluir pelo menos uma outra letra, número ou sublinhado. Você deve considerar a nomeação de variáveis com uma taxonomia legível por humanos que tenha significado ou contexto para outras pessoas, para que seu código seja fácil de interpretar e não exija engenharia reversa para compreender sua finalidade.
Por exemplo, se você estiver definindo uma variável que deriva um valor de pontuação de propensão dos dados do cliente, considere usar um nome como @propensityScore , não @ps. Além disso, pode ser útil aplicar a notação camel case para nomes de variáveis que são compostos por mais de uma palavra colocando as palavras subsequentes em maiúsculas. Por exemplo, uma variável nomeada @preferredContactNumber é mais fácil de ler do que @preferredcontactnumber.
1.6.2. Declarando variáveis
Antes que uma variável possa ser definida , ela deve ser declarada. As variáveis são declaradas com a var palavra-chave, seguida por um ou mais nomes de variáveis delimitados por vírgulas. Por exemplo, se você precisar definir o nome, o sobrenome e a data de expiração da associação de um membro, as variáveis podem ser declaradas como:
var @firstName, @lastName, @membershipExpiryDate
declaração de uma variável adiciona uma entrada a um Dicionário de variáveis interno, usando o nome da variável como chave e null como valor. Se já existir uma entrada para esse nome, o valor da variável será redefinido para null.
NOTA: AMPscript é uma linguagem de tipagem flexível e, como resultado, o interpretador não obriga a declaração de variáveis. No entanto, é uma prática recomendada fazer isso para garantir que o nome da variável seja adicionado ao Dicionário de variáveis.
1.6.3. Variáveis de configurações
Depois que uma variável é declarada, ela pode ser definida. As variáveis são definidas usando uma sintaxe que compreende quatro elementos:
um único símbolo de igual (=) uma string de personalização , constante ou função AMPscript (que pode conter funções aninhadas). Consulte o exemplo abaixo, onde as variáveis são definidas como uma string de personalização ( @firstName), função AMPscript ( @localDate) e constante ( @promotionEndDate):
%%[
var @firstName, @localDate, @promotionEndDate
set @firstName = FirstName
set @localDate = SystemDateToLocalDate(Now())
set @promotionEndDate = '10/15/2018'
]%%
var @firstName, @localDate, @promotionEndDate: Aqui, três variáveis são declaradas: @firstName, @localDate e @promotionEndDate. set @firstName = FirstName: Essa linha atribui o valor da variável personalizada FirstName à variável @firstName. set @localDate = SystemDateToLocalDate(Now()): Aqui, a função Now() é usada para obter a data e a hora atuais do sistema no formato GMT (hora padrão). Em seguida, a função SystemDateToLocalDate() é usada para converter essa data e hora para o fuso horário local. O resultado é armazenado na variável @localDate set @promotionEndDate = '10/15/2018': Aqui, uma data específica, neste caso, '10/15/2018', é atribuída à variável @promotionEndDate. Isso pode indicar a data de término de uma promoção ou evento. Resumindo, esse código em AMPscript é usado para:
Armazenar o nome do destinatário na variável @firstName. Obter a data e hora atuais no fuso horário local e armazená-las na variável @localDate. Definir uma data específica ('10/15/2018') na variável @promotionEndDate. 1.6.4. Escopo
Depois que uma variável é definida, seu escopo é definido globalmente; ou seja, pode ser referenciado posteriormente no código para exibir a saída ou usado em expressões condicionais. No entanto, as variáveis também podem ser alteradas depois de terem sido definidas. Por exemplo, a data de término de uma promoção é definida em um campo em uma extensão de dados enviáveis usando uma string de personalização, mas para clientes específicos, há um requisito para ajustar esse valor posteriormente no código:
%%[
var @promotionEndDate, @memberStatus
set @promotionEndDate = '10/15/2018'
set @memberStatus = status
if @memberStatus == 'gold' then
set @promotionEndDate = '11/15/2018'
endif
]%%
As variáveis também podem ser definidas em si mesmas em uma função; ou seja, se a variável foi declarada anteriormente, ela pode ser usada como argumento para uma função, com base em seu valor anterior. Portanto, o código acima também pode ser expresso como:
%%[
var @promotionEndDate, @memberStatus
set @promotionEndDate = '10/15/2018'
set @memberStatus = status
if @memberStatus == 'gold' then
set @promotionEndDate = DateAdd(@promotionEndDate, 1, 'M')
endif
]%%
Além disso, uma vez que uma variável tenha sido definida, ela pode ser redefinida declarando o valor novamente. No exemplo abaixo, se a data atual for menor que (após) a data de término da associação, um null valor será definido para o status da associação.
%%[
var @membershipEndDate, @memberStatus
set @membershipEndDate = '10/15/2018'
set @memberStatus = status
if @membershipEndDate > Now() then
var @memberStatus
endif
]%%
A única exceção a esta regra de escopo é quando uma variável é usada dentro de um for bloco. Nesse cenário, a variável está bloqueada para modificação dentro do loop do processo .
1.6.5. Ordem de operações
Como outras linguagens de script, o AMPscript é interpretado de cima para baixo, o que significa que as variáveis devem ser declaradas e definidas antes de serem usadas. No entanto, os componentes de e-mail são interpretados na seguinte ordem:
Por exemplo, uma variável pode ser declarada e definida em um corpo HTML (dentro de um bloco AMPscript) e usada em uma linha de assunto:
<!--Appears in Body-->
%%[
var @subjectLine
if AttributeValue('Member Status') == 'VIP' then
set @subjectLine = 'An exclusive offer for VIP members'
else
set @subjectLine = 'A special offer for our members'
endif
]%%
<!--Appears in Subject Line-->
%%=v(@subjectLine)=%%
OBSERVAÇÃO: funções AMPscript aninhadas e variáveis aninhadas não serão processadas em linhas de assunto a partir de 21 de fevereiro de 2023. Consulte este documento de ajuda para obter mais informações sobre essa alteração.
1.6.6. Usando variáveis
As variáveis não são necessárias no AMPscript. É possível obter o mesmo resultado usando apenas funções, declarações condicionais e operadores. No entanto, sem variáveis:
funções e constantes precisariam ser definidas várias vezes, geralmente resultando em mais código e dificultando a manutenção cada função AMPscript duplicada precisa ser interpretada novamente, resultando em possíveis problemas de desempenho ao enviar e-mails ou renderizar conteúdo. O exemplo abaixo indica a inclusão de duas variáveis no AMPscript para recuperar um saldo de pontos e exibir um nível de status correspondente.
%%[
var @pointsBalance, @status
set @pointsBalance = Lookup("Points Balance","Balance","MemberId", _subscriberKey)
if @pointsBalance < 100 then
set @status = "bronze"
elseif @pointsBalance > 100 and @pointsBalance < 500 then
set @status = "silver"
else
set @status = "gold"
endif
]%%
You are a valued %%=v(@status)=%% member.
Ao escrever AMPscript, é uma boa prática otimizar seu código por meio da configuração de variáveis para funções comumente usadas.
1.7. Comentário
Os comentários podem ser incluídos nos blocos AMPscript. Eles estão contidos em um par de sintaxe de abertura /*e fechamento */e fornecem a capacidade de incluir uma explicação ou anotação legível para os usuários. Quaisquer comentários são ignorados pelo Marketing Cloud e não serão interpretados. Eles podem ser usados em uma única linha ou percorrer várias linhas.
Exemplo 1
Este é um exemplo de comentário de uma linha:
%%[ /* Este é um exemplo de comentário de uma linha em AMPscript. */
set @variable = "valor"
]%%
Exemplo 2
Aqui está um exemplo de um comentário que atravessa várias linhas:
%%[
/*
Este é um exemplo de um comentário
que se estende por várias linhas em AMPscript.
Pode ser usado para explicar partes mais extensas
do código ou fornecer informações detalhadas.
*/
set @variable = "valor"
]%%
1.8. Function calls
As funções são interpretadas ou 'chamadas' dentro de um bloco AMPscript ou AMPscript embutido, no local onde aparecem na página ou na mensagem. No entanto, as funções não precisam estar contidas no mesmo bloco AMPscript. Por exemplo, ao usar instruções condicionais , a expressão condicional pode abranger vários blocos:
%%[
var @balance
set @balance = Lookup('Points Balance', 'Balance', 'MemberId', _subscriberKey)
]%%
%%[ if @balance < 100 then ]%%
You are a valued bronze member.
%%[ elseif @balance > 100 and @balance < 500 then ]%%
You are a valued silver member.
%%[ else ]%%
You are a valued gold member.
%%[ endif ]%%
Da mesma forma, podem (e normalmente o fazem) abranger vários blocos, conforme indicado abaixo. <h2>Your Order Items</h2>
<ul>
%%[
var @orderId, @rows, @row, @rowCount, @i
set @orderId = AttributeValue("OrderId")
set @rows = LookupRows("Orders","OrderId", @orderId)
set @rowCount = rowcount(@rows)
if @rowCount > 0 then
for @i = 1 to @rowCount do
var @name, @value
set @row = row(@rows, @i)
set @name = field(@row,"Name")
set @value = field(@row,"Value")
]%%
<li>%%=v(@name)=%%, $%%=v(@value)=%%</li>
%%[ next @i ]%%